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Foreword 


1 ISO (the International Organization for Standardization) and IEC (the Interna- 

2 tional Electrotechnical Commission) together form a system for worldwide stan- 

3 dardization as a whole. National bodies that are members of ISO or IEC partid- 

4 pate in the development of International Standards through technical committees 

5 established by the respective organization to deal with particular fields of techni- 

6 cal activity. ISO and IEC technical committees collaborate in fields of mutual 

7 interest. Other international organizations, governmental and nongovernmental, 
s in liaison with ISO and IEC, also take part in the work. 

9 In the field of information technology, ISO and IEC have established a joint techni- 

10 cal committee, ISO/IEC JTC 1. Draft International Standards adopted by the joint 

11 technical committee are circulated to national bodies for approval before their 

12 acceptance as International Standards. They are approved in accordance with 

13 procedures requiring at least 75% approval by the national bodies voting. 

14 International Standard ISO/IEC 9945-1: 1990 was prepared by Joint Technical 
is Committee ISO/IEC JTC 1, Information technology. 

16 ISO/IEC 9945 consists of the following parts, under the general title Information 

17 technology — Portable operating system interface (POSIX) : 

18 — Part 1: System application program interface (API) [C language] 

19 — Part 2: Shell and utilities (under development) 

20 — Part 3: System administration (under development) 

2 1 Annexes A to E of ISO/IEC 9945-1 are provided for information only. 
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(This Introduction is not a normative part of ISO/IEC 9945-1 Information technology — Portable 
operating system interface (POSIX) — Part 1: System application programming interface (API) 
[C Language], but is included for information only.) 

1 The purpose of this part of ISO/IEC 9945 is to define a standard operating system 

2 interface and environment based on the UNIX 1 * Operating System documentation 

3 to support application portability at the source level. This is intended for systems 

4 implementors and applications software developers. 

6 Initially, 2 * the focus of this part of ISO/IEC 9945 is to provide standardized ser- 

6 vices via a C language interface. Future revisions are expected to contain bind- 

7 ings for other programming languages as well as for the C language. This will be 

8 accomplished by breaking this part of ISO/IEC 9945 into multiple portions — one 

9 defining core requirements independent of any programming language, and oth- 

10 ers composed of programming language bindings. 

n The core requirements portion will define a set of required services common to 

12 any programming language that can be reasonably expected to form a language 

13 binding to this part of ISO/IEC 9945. These services will be described in terms of 

14 functional requirements and will not define programming language-dependent 

15 interfaces. Language bindings will consist of two m^jor parts. One will contain 

16 the programming language’s standardized interface for accessing the core services 

17 defined in the programming language-independent core requirements section of 

is this part of ISO/IEC 9945. The other will contain a standardized interface for 

19 language-specific services. Any implementation claiming conformance to this part 

20 of ISO/IEC 9945 with any language binding will be required to comply with both 

21 sections of the language binding. 

22 Within this document, the term “POSIX.1" refers to this part of ISO/IEC 9945 

23 itself. 

24 Organization of This Part of ISO/IEC 9945 

25 This part of ISO/IEC 9945 is divided into four elements: 

26 (1) Statement of scope and list of normative references (Section 1) 

27 (2) Definitions and global concepts (Section 2) 

28 (3) The various interface facilities (Sections 3 through 9) 

29 (4) Data interchange format (Section 10) 


30 1) UNIX is a registered trademark of AT&T in the USA and other countries. 

31 2) The vertical rules in the right margin depict technical or significant non-editorial changes from 

32 IEEE Std 1003.1-1988 to IEEE Std 1003.1-1990. A vertical rule beside an empty line indicates 

33 deleted text. 
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34 Most of the sections describe a single service interface. The C Language binding 

36 for the service interface is given in the subclause labeled Synopsis. The Descrip- 

36 tion subclause provides a specification of the operation performed by the service 

37 interface. Some examples may be provided to illustrate the interfaces described. 

38 In most cases there are also Returns and Errors subclauses specifying return 

39 values and possible error conditions. References are used to direct the reader to 

40 other related sections. Additional material to complement sections in this part of 

41 ISO/IEC 9945 may be found in the Rationale and Notes, Annex B. This annex pro- 

42 vides historical perspectives into the technical choices made by the developers of 

43 this part of ISO/IEC 9945. It also provides information to emphasize consequences 

44 of the interfaces described in the corresponding section of this part of 

46 ISO/IEC 9945. 

46 Informative annexes are not part of the standard and are provided for information 

47 only. (There is a type of annex called “normative” that is part of a standard and 

48 imposes requirements, but there are currently no such normative annexes in this 

49 part of ISO/IEC 9945.) They are provided for guidance and to help understanding. 

60 In publishing this part of ISO/IEC 9945, its developers simply intend to provide a 

61 yardstick against which various operating system implementations can be meas- 

62 ured for conformance. It is not the intent of the developers to measure or rate any 

63 products, to reward or sanction any vendors of products for conformance or lack of 

64 conformance to this part of ISO/IEC 9945, or to attempt to enforce this part of 

66 ISO/IEC 9945 by these or any other means. The responsibility for determining the 

66 degree of conformance or lack thereof with this part of ISO/IEC 9945 rests solely 

67 with the individual who is evaluating the product claiming to be in conformance 

68 with this part of ISO/IEC 9945. 

69 Base Documents 

60 The various interface facilities described herein are based on the 1984 /usr/ group 

61 Standard derived and published by the UniForum (formerly /usr/group) Stan- | 

62 dards Committee. The 1984 /usr / group Standard and this part of ISO/IEC 9945 

63 are largely based on UNIX Seventh Edition, UNIX System III, UNIX System' V, 

64 4.2BSD, and 4.3BSD documentation, 3) but wherever possible, compatibility with 

66 other systems derived from the UNIX operating system, or systems compatible 

66 with that system, has been maintained. 

67 Background j 

68 The developers of P0SIX.1 represent a cross-section of hardware manufacturers, | 

69 vendors of operating systems and other software development tools, software 

70 designers, consultants, academics, authors, applications programmers, and oth- 

71 ers. In the course of their deliberations, the developers reviewed related Ameri- | 

72 can and international standards, both published and in progress. | 

73 Conceptually, POSIX.l describes a set of fundamental services needed for the | 

74 efficient construction of application programs. Access to these services has been | 

76 3) The IEEE is grateful to both AT&T and UniForum for permission to use their materials. 
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provided by defining an interface, using the C programming language, that estab- 
lishes standard semantics and syntax. Since this interface enables application 
writers to write portable applications — it was developed with that goal in mind — 
it has been designated POSIX, 4) an acronym for Portable Operating System 
Interface. 

Although originated to refer to IEEE Std 1003.1-1988, the name POSIX more | 
correctly refers to a family of related standards: IEEE 1003 . n and the parts of | 
International Standard ISO/IEC 9945. In earlier editions of the IEEE standard, | 
the term POSIX was used as a synonym for IEEE Std 1003.1-1988. A preferred | 
term, POSIX.1, emerged. This maintained the advantages of readability of the | 
symbol “POSIX” without being ambiguous with the POSIX family of standards. I 

Audience 

The intended audience for ISO/IEC 9945 is all persons concerned with an 
industry-wide standard operating system based on the UNIX system. This 
includes at least four groups of people: 

(1) Persons buying hardware and software systems; 

(2) Persons managing companies that are deciding on future corporate com- 
puting directions; 

(3) Persons implementing operating systems, and especially 

(4) Persons developing applications where portability is an objective. 

Purpose 

Several principles guided the development of this part of ISO/IEC 9945: I 

Application Oriented 

The basic goal was to promote portability of application programs across | 
UNIX system environments by developing a clear, consistent, and unam- 
biguous standard for the interface specification of a portable operating 
system based on the UNIX system documentation. This part of 
ISO/IEC 9945 codifies the common, existing definition of the UNIX sys- 
tem. There was no attempt to define a new system interface. 


106 Interface, Not Implementation 

loe This part of ISO/IEC 9945 defines an interface, not an implementation. 

107 No distinction is made between library functions and system calls: both 

loe are referred to as functions. No details of the implementation of any 

109 function are given (although historical practice is sometimes indicated 

no in Annex B). Symbolic names are given for constants (such as signals 

in and error numbers) rather than numbers. 


112 4) The name POSIX was suggested by Richard Stallman. It is expected to be pronounced pahz-icks, 

113 as in positive, not poh-six, or other variations. The pronunciation has been published in an 

114 attempt to promulgate a standardized way of referring to a standard operating system interface. 
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Source, Not Object, Portability 

This part of ISO/IEC 9945 has been written so that a program written 
and translated for execution on one conforming implementation may 
also be translated for execution on another conforming implementation. 
This part of ISO/IEC 9945 does not guarantee that executable (object or 
binary) code will execute under a different conforming implementation 
than that for which it was translated, even if the underlying hardware 
is identical. However, few impediments were placed in the way of 
binary compatibility, and some remarks on this are found in Annex B. 
See B. 1.3. 1.1 and B.4.8. 

The C Language 

This part of ISO/IEC 9945 is written in terms of the standard C language 
as specified in the C Standard {2}. 5 6) See B.1.3 and B.l.1.1. 

No Super-User, No System Administration 

There was no intention to specify all aspects of an operating system. 
System administration facilities and functions are excluded from 
POSIX.l, and functions usable only by the super-user have not been 
included. Annex B notes several such instances. Still, an implementa- 
tion of the standard interface may also implement features not in this 
part of ISO/IEC 9945; see 1.3. 1.1. This part of ISO/IEC 9945 is also not 
concerned with hardware constraints or system maintenance. 

Minimal Interface, Minimally Defined 

In keeping with the historical design principles of the UNIX system, 
POSIX.1 is as minimal as possible. For example, it usually specifies only 
one set of functions to implement a capability. Exceptions were made in 
some cases where long tradition and many existing applications 
included certain functions, such as creat(). In such cases, as throughout 
POSIX1, redundant definitions were avoided: creatO is defined as a spe- 
cial case of open (). Redundant functions or implementations with less 
tradition were excluded. 

Broadly Implementable 

The developers of POSIX.l endeavored to make all specified functions 
implementable across a wide range of existing and potential systems, 
including: 

(1) All of the current major systems that are ultimately derived from 
the original UNIX system code (Version 7 or later) 

(2) Compatible systems that are not derived from the original UNIX 
system code 


5) The number in braces corresponds to those of the references in 1.2 (or the bibliographic entry in 

Annex A if the number is preceded by the letter B). 
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(3) Emulations hosted on entirely different operating systems 

(4) Networked systems 

(5) Distributed systems 

(6) Systems running on a broad range of hardware 

No direct references to this goal appear in this part of ISO/IEC 9945, but 
some results of it are mentioned in Annex B. 

Minimal Changes to Historical Implementations 

There are no known historical implementations that will not have to 
change in some area to conform to this part of ISO/IEC 9945, and in a 
few areas POSIX.l does not exactly match any existing system interface 
(for example, see the discussion of 0_N0NBL0CK in B.6). Nonetheless, 
there is a set of functions, types, definitions, and concepts that form an 
interface that is common to most historical implementations. POSIX1 
specifies that common interface and extends it in areas where there has 
historically been no consensus, preferably 

(1) By standardizing an interface like one in an historical implemen- 
tation; e.g., directories, or; 

(2) By specifying an interface that is readily implementable in terms 
of, and backwards compatible with, historical implementations, 
such as the extended tar format in 10.1.1, or; 

(3) By specifying an interface that, when added to an historical imple- 
mentation, will not conflict with it, like B.6. 

Required changes to historical implementations have been kept to a 
minimum, but they do exist, and Annex B points out some of them. 

POSIX1 is specifically not a codification of a particular vendor’s product. 
It is similar to the UNIX system, but it is not identical to it. 

It should be noted that implementations will have different kinds of 
extensions. Some will reflect “historical usage” and will be preserved for 
execution of pre-existing applications. These functions should be con- 
sidered “obsolescent” and the standard functions used for new applica- 
tions. Some extensions will represent functions beyond the scope of 
POSIX.1. These need to be used with careful management to be able to 
adapt to future POSIX1 extensions and/or port to implementations that 
provide these services in a different manner. 

Minimal Changes to Existing Application Code 

A goal of POSIX1 was to minimize additional work for the developers of 
applications. However, because every known historical implementation 
will have to change at least slightly to conform, some applications will 
have to change. Annex B points out the major places where POSIX.1 
implies such changes. 
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195 Related Standards Activities 


I 

196 Activities to extend this part of ISO/IEC 9945 to address additional requirements 

197 are in progress, and similar efforts can be anticipated in the future. 

198 The following areas are under active consideration at this time, or are expected to 

199 become active in the near future: 6 * 

200 (1) Language-independent service descriptions of this part of ISO/IEC 9945 

201 (2) C, Ada, and FORTRAN Language bindings to (1) 

202 (3) Shell and Utility facilities 

203 (4) Verification testing methods 

204 (5) Realtime facilities 

205 (6) Secure/Trusted System considerations 

206 (7) Network interface facilities 

207 (8) System Administration 

208 (9) Graphical User Interfaces 

209 (10) Profiles describing application- or user-specific combinations of Open Sys- 

210 terns standards for: supercomputing, multiprocessor, and batch exten- 

2 11 sions; transaction processing; realtime systems; and multiuser systems 

212 based on historical models 

213 (11) An overall guide to POSIX-based or related Open Systems standards and 

214 profiles 

216 Extensions are approved as “amendments” or “revisions” to this document, follow- 

216 ing the IEEE and ISO/IEC Procedures. 

217 Approved amendments are published separately until the full document is 

218 reprinted and such amendments are incorporated in their proper positions. 

219 If you have interest in participating in the TCOS working groups addressing these 

220 issues, please send your name, address, and phone number to the Secretary, IEEE 

221 Standards Board, Institute of Electrical and Electronics Engineers, Inc., P.O. Box 

222 1331, 445 Hoes Lane, Piscataway, NJ 08855-1331, and ask to have this forwarded 

223 to the chairperson of the appropriate TCOS working group. If you have interest in 

224 participating in this work at the international level, contact your ISO/IEC national 
226 body. 


6) A Standards Status Report that lists all current IEEE Computer Society standards projects is 
available from the IEEE Computer Society, 1730 Massachusetts Avenue NW, Washington, DC 
20036-1903; Telephone: 4-1 202 371-0101; FAX: +1 202 728-9614. Working drafts of POSDC 
standards under development are also available from this office. 
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INTERNATIONAL STANDARD 


ISO/IEC 9945-1: 1990 


Information technology— Portable operating 
system interface (POSIX) — Part 1: System 
application programming interface (API) 

[C Language] 


Section 1: General 


1 1.1 Scope 

2 This part of ISO/IEC 9945 defines a standard operating system interface and 

3 environment to support application portability at the source-code level. It is 

4 intended to be used by both application developers and system implementors. 

5 This part of ISO/IEC 9945 comprises four major components: 

6 (1) Terminology, concepts, and definitions and specifications that govern 

7 structures, headers, environment variables, and related requirements 

e (2) Definitions for system service interfaces and subroutines 

9 (3) Language-specific system services for the C programming language 

10 (4) Interface issues, including portability, error handling, and error recovery 

11 The following areas are outside of the scope of this part of ISO/IEC 9945. 

12 (1) User interface (shell) and associated commands 

13 (2) Networking protocols and system call interfaces to those protocols 

14 (3) Graphics interfaces 

is (4) Database management system interfaces 

16 (5) Record I/O considerations 
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17 (6) Object or binary code portability 

is (7) System configuration and resource availability 

19 (8) The behavior of system services on systems supporting concurrency 

20 within a single process 

21 This part of ISO/IEC 9945 describes the external characteristics and facilities that 

22 are of importance to applications developers, rather than the internal construc- 

23 tion techniques employed to achieve these capabilities. Special emphasis is 

24 placed on those functions and facilities that are needed in a wide variety of com- 

25 mercial applications. 

26 This part of ISO/IEC 9945 has been defined exclusively at the source-code level. 

27 The objective is that a Strictly Conforming POSIX.l Application source program 

28 can be translated to execute on a conforming implementation. 


29 1.2 Normative References I 

30 The following standards contain provisions which, through references in this text, | 

:u constitute provisions of this part of ISO/IEC 9945. At the time of publication, the | 

32 editions indicated were valid. All standards are subject to revision, and parties to | 

33 agreements based on this part of this International Standard are encouraged to | 

34 investigate the possibility of applying the most recent editions of the standards | 

35 listed below. Members oflEC and ISO maintain registers of currently valid Inter- | 

36 national Standards. I 

37 {1} ISO/IEC 646: 1983, Information processing — ISO 7-bit coded character set \ 

38 for information interchange. I 

39 {2} ISOAEC 9899 \ ... t 2) Information technology — Programming languages — C. | 


40 1.3 Conformance 

41 1.3.1 Implementation Conformance 

42 1.3. 1.1 Requirements 

43 A conforming implementation shall meet all of the following criteria: 


44 1) Under revision. (This notation is meant to explicitly reference the 1990 Draft International 

45 Standnrd version of ISO/IEC 646.) 

46 ISO/IEC documents can be obtained from the ISO office, 1, rue de Varemb6, Case Postale 56, CH- 

47 1211, Genfeve 20, Switzerland/Suisse. 

48 2) To be approved and published. 
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49 (1) The system shall support all required interfaces defined within this part 

so of ISO/IEC 9945. These interfaces shall support the functional behavior 

51 described herein. 

52 (2) The system may provide additional functions or facilities not required by 

63 this part of ISOAEC 9945. Nonstandard extensions should be identified 

64 as such in the system documentation. Nonstandard extensions, when 

65 used, may change the behavior of functions or facilities defined by this 

66 part of ISOAEC 9945. The conformance document shall define an | 

67 environment in which an application can be run with the behavior | 

58 specified by the standard. In no case shall such an environment require 

59 modification of a Strictly Conforming POSIX.l Application. 

\ 

60 1.3.1.2 Documentation 

61 A conformance document with the following information shall be available for an 

62 implementation claiming conformance to this part of ISO/IEC 9945. The confor- 

• 63 mance document shall have the same structure as this part of ISO/IEC 9945, with 

64 the information presented in the appropriately numbered sections, clauses, and 

65 subclauses. The conformance document shall not contain information about 

66 extended facilities or capabilities outside the scope of this part of ISO/IEC 9945. 

67 The conformance document shall contain a statement that indicates the full 

68 name, number, and date of the standard that applies. The conformance document 

69 may also list international software standards that are available for use by a Con- 

70 forming POSIX.l Application. Applicable characteristics where documentation is 

71 required by one of these standards, or by standards of government bodies, may 

72 also be included. 

73 The conformance document shall describe the limit values found in the | 

74 <limits.h> and <unistd.h> headers, stating values, the conditions under 
76 which those values may change, and the limits of such variations, if any. 

76 The conformance document shall describe the behavior of the implementation for 

77 all implementation-defined features defined in this part of ISO/IEC 9945. This 

78 requirement shall be met by listing these features and providing either a specific | 

79 reference to the system documentation or providing full syntax and semantics of | 

so these features. The conformance document may specify the behavior of the imple- | 

81 mentation for those features where this part of ISO/IEC 9945 states that imple- | 

82 mentations may vary or where features are identified as undefined or unspecified. | 

83 No specifications other than those described in this part of ISO/IEC 9945 shall be | 

84 present in the conformance document. I 

85 The phrases “shall document” or “shall be documented” in this part of | 

86 ISO/IEC 9945 mean that documentation of the feature shall appear in the confor- | 

87 mance document, as described previously, unless the system documentation is | 

88 explicitly mentioned. I 

89 The system documentation should also contain the information found in the con- | 

90 form an ce document. I 
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91 1.3. 1.3 Conforming Implementation Options 

92 The following symbolic constants, described in the subclauses indicated, reflect | 

93 implementation options for this part of ISO/IEC 9945 that could warrant require- 

94 ment by Conforming POSIX1 Applications, or in specifications of conforming sys- 

95 terns, or both: 

96 (NGROUPSJMAX) Multiple groups option (in 2.8.3) 

97 {_POSIX_JOB_CONTROL} Job control option (in 2.9.3) 

98 LPOSIX^CHOWN_RESTRICTED) Administrative/security option (in 2.9.4) 

99 The remaining symbolic constants in 2.9.3 and 2.9.4 are useful for testing pur- 

100 poses and as a guide to applications on the types of behaviors they need to be able 

101 to accommodate. They do not reflect sufficient functional difference to warrant 

102 requirement by Conforming POSIX.1 Applications or to distinguish between con- 

103 forming implementations. 

104 In the cases where omission of an option would cause functions described by this 

ior> part of ISO/IEC 9945 to not be defined, an implementation shall provide a function 

loo that is callable with the syntax defined in this part of ISO/IEC 9945, even though 

107 in an instance of the implementation the function may always do nothing but 

108 return an error. 

109 1.3.2 Application Conformance 

no All applications claiming conformance to this part of ISO/IEC 9945 shall use only 

111 language-dependent services for the C programming language described in 1.3.3 

112 and shall fall within one of the following categories: 

113 1.3.2.1 Strictly Conforming POSIX.1 Application 

in A Strictly Conforming POSIX.1 Application is an application that requires only the 

ns facilities described in this part of ISO/IEC 9945 and the applicable language stan- 

116 dards. Such an application shall accept any behavior described in this part of 

in ISO/IEC 9945 as unspecified or implementation-defined , and for symbolic con- | 

ns stants, shall accept any value in the range permitted by this part of ISO/IEC 9945. 

119 Such applications are permitted to adapt to the availability of facilities whose 

120 availability is indicated by the constants in 2.8 and 2.9. 

121 I.3.2.2 Conforming POSIX.1 Application 

122 1.3.2.2.1 ISO/IEC Conforming POSIX.1 Application I 

123 An ISO/IEC Conforming POSIX 1 Application is an application that uses only the | 

124 facilities described in this part of ISO/IEC 9945 and approved Conforming | 

125 Language bindings for any ISO or IEC standard. Such an application shall | 

126 include a statement of conformance that documents all options and limit depen- | 

127 dencies, and all other ISO or IEC standards used. . I 
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128 1.3.2.2.2 <National Body> Conforming POSEX1 Application 

129 A <National Body> Conforming POSIX 1 Application differs from an ISO/IEC Con- 

130 forming POSIX.1 Application in that it also may use specific standards of a single 

131 ISO/IEC member body referred to here as “ <National Body>. n Such an application 

132 shall include a statement of conformance that documents all options and limit 

133 dependencies, and all other <National Body> standards used. 

134 1.3.2.3 Conforming POSIX.1 Application Using Extensions 

136 A Conforming POSIX1 Application Using Extensions is an application that differs 

136 from a Conforming POSIX 1 Application only in that it uses nonstandard facilities 

137 that are consistent with this part of ISO/IEC 9945. Such an application shall fully 

138 document its requirements for these extended facilities, in addition to the docu- 

139 mentation required of a Conforming POSIX 1 Application. A Conforming POSIX 1 

140 Application Using Extensions shall be either an ISO/IEC Conforming POSIX 1 

141 Application Using Extensions or a <National Body> Conforming POSIX 1 Applica- 

142 tion Using Extensions (see 1.3.2.2.1 and 1.3.2.2.2). 

143 1.3.3 Language-Dependent Services for the C Programming Language 

144 Parts of ISO/IEC 9899 {2} (hereinafter referred to as the “C Standard {2}”) will be | 

145 referenced to describe requirements also mandated by this part of ISO/IEC 9945. 

146 The sections of the C Standard {2} referenced to describe requirements for this 

147 part of ISO/IEC 9945 are specified in Section 8. Section 8 also sets forth additions 

148 and amplifications to the referenced sections of the C Standard {2}. Any imple- 

149 mentation claiming conformance to this part of ISO/IEC 9945 with the C Language 

iso Binding shall provide the facilities referenced in Section 8, along with any addi- 

151 tions and amplifications Section 8 requires. 

162 Although this part of ISO/IEC 9945 references parts of the C Standard (2) to 

163 describe some of its own requirements, conformance to the C Standard {2} is 

164 unnecessary for conformance to'lhis part of ISO/IEC 9945. Any C language imple- 

i 156 mentation providing the facilities stipulated in Section 8 may claim conformance; | 

156 however, it shall clearly state that its C language does not conform to the | 

167 C Standard (2). 

168 1. 3.3.1 Types of Conformance 

169 Implementations claiming conformance to this part of ISO/IEC 9945 with the C 
iso Language Binding shall claim one of two types of conformance — conformance to | 

161 POSIX.1, C Language Binding (C Standard Language-Dependent System Sup- | 

162 port), or to POSIX.1, C Language Binding (Common-Usage C Language-Dependent | 

163 System Support). 

164 1. 3.3.2 C Standard Language-Dependent System Support 

165 Implementors shall meet the requirements of Section 8 using for reference the 

166 C Standard {2}. Implementors shall clearly document the version of the 

167 C Standard {2} referenced in fulfilling the requirements of Section 8. 
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168 Implementors seeking to claim conformance using the C Standard { 2 } shall claim I 

169 conformance to POSIX. 1 , C Language Binding (C Standard Language-Dependent | 

no System Support). I 

171 1 .3.3.3 Common-Usage C Language-Dependent System Support 

172 Implementors, instead of referencing the C Standard ( 2 ), shall provide the rou- 

173 tines and support required in Section 8 using common usage as guidance. Imple- 

174 mentors shall meet all the requirements of Section 8 except where references are 

176 made to the C Standard ( 2 ). In places where the C Standard ( 2 ) is referenced, 

176 implementors shall provide equivalent support in a manner consistent with com- 

177 mon usage of the C programming language. Implementors shall document, in | 

178 Section 8 of the conformance document, all differences between the interface pro- | 

179 vided and the interface that would have been provided had the C Standard ( 2 ) | 

iso been implemented instead of common usage. Implementors shall clearly docu- | 

lai ment the version of the C Standard { 2 } referenced in documenting interface differ- 

182 ences and should issue updates on differences for all new versions of the 

183 C Standard { 2 }. 

184 I 

185 Where a function has been introduced by the C Standard ( 2 ), and thus there is no 

186 common-usage referent for it, if the function is implemented, it shall be imple- 

187 mented as described in the C Standard ( 2 ). If the function is not implemented, it 

188 shall be documented as a difference from the C Standard { 2 } as required above. 

189 1.3.4 Other C Language-Related Specifications 

190 The following rules apply to the usage of C language library functions; each of the 

191 statements in this subclause applies to the detailed function descriptions in Sec- 

192 tions 3 through 9 , unless explicitly stated otherwise: 

193 ( 1 ) If an argument to a function has an invalid value (such as a value outside 

194 the domain of the function, or a pointer outside the address space of the 

195 program, or a NULL pointer when that is not explicitly permitted), the 

196 behavior is undefined. 

197 ( 2 ) Any function may also be implemented as a macro in a header. Applica- 

198 tions should use #undef to remove any macro definition and ensure that 

199 an actual function is referenced. Applications should also use #undef 

200 prior to declaring any function in this part of ISO/IEC 9945 . 

201 ( 3 ) Any invocation of a library function that is implemented as a macro shall 

202 expand to code that evaluates each of its arguments only once, fully pro- 

203 tected by parentheses where necessary, so it is generally safe to use arbi- 

204 trary expressions as arguments. 

205 ( 4 ) Provided that a library function can be declared without reference to any 

206 type defined in a header, it is also permissible to declare the function, 

207 either explicitly or implicitly, and use it without including its associated 

208 header. 
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( 5 ) If a function that accepts a variable number of arguments is not declared 
(explicitly or by including its associated header), the behavior is 
undefined. 


212 1.3.5 Other Language-Related Specifications 

213 This part of ISO/IEC 9945 is currently specified in terms of the language defined 

214 by the C Standard ( 2 ). Bindings to other programming languages are being 
216 developed. 

216 If conformance to this part of ISO/IEC 9945 is claimed for implementation of any 

217 programming language, the implementation of that language shall support the 

218 use of external symbols distinct to at least 31 bytes in length in the source pro- 

219 gram text. (That is, identifiers that differ at or before the thirty-first byte shall be 

220 distinct.) If a national or international standard governing a language defines a 

221 maximum length that is less than this value, the language-defined maximum 

222 shall be supported. External symbols that differ only by case shall be distinct 

223 when the character set in use distinguishes upper- and lowercase characters and 

224 the language permits (or requires) upper- and lowercase characters to be distinct 

225 in external symbols. 

226 Subsequent sections of this part of ISO/IEC 9945 refer only to the C Language. 
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Section 2: Terminology and General Requirements 


2.1 Conventions 


This part of ISO/IEC 9945 uses the following typographic conventions: 

(1) The italic font is used for: 

— Cross references to defined terms within 1.3, 2.2.1, and 2.2.2; symbolic 
parameters that are generally substituted with real values by the 
application 

— C language data types and function names (except in function 
Synopsis subclauses) 

— Global external variable names 

(2) The bold font is used with a word in all capital letters, such as 

PATH 

to represent an environment variable, as described in 2.6. It is also used 
for the term “NULL pointer.” 

(3) The constant-width (Courier) font is used: 

For C language data types and function names within function 

Synopsis subclauses 

— To illustrate examples of system input or output where exact usage is 
depicted 

— For references to utility names and C language headers 

(4) Symbolic constants returned by many functions as error numbers are 
represented as: 

[ERRNO] 

See 2.4. 

(5) Symbolic constants or limits defined in certain headers are represented 


(LIMIT) 

See 2.8 and 2.9. 

In some cases tabular information is presented “inline”; in others it is presented 
in a separately labeled table. This arrangement was employed purely for ease of 
typesetting and there is no normative difference between these two cases. 
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31 The conventions listed previously are for ease of reading only. Editorial incon- | 

32 sistencies in the use of typography are unintentional and have no normative 

33 meaning in this part of ISO/IEC 9945. 

34 NOTEs provided as parts of labeled tables and figures are integral parts of this | 

35 part of ISO/IEC 9945 (normative). Footnotes and notes within the body of the text j 

36 are for information only (informative). | 

37 Numerical quantities are presented in international style: comma is used as a | 

38 decimal sign and units are from the International System (SI). I 


39 2.2 Definitions 


40 2.2.1 Terminology 

41 For the purposes of this part of ISO/IEC 9945, the following definitions apply: | 

42 2.2. 1.1 conformance document: A document provided by an implementor that | 

43 contains implementation details as described in 1. 3.1.2. i 

44 2.2. 1.2 implementation defined: An indication that the implementation shall | 

45 define and document the requirements for correct program constructs and correct j 

46 data of a value or behavior. 

I 

47 2.2. 1.3 may: An indication of an optional feature. | 

48 With respect to implementations, the word may is to be interpreted as an optional 

49 feature that is not required in this part of ISO/IEC 9945, but can be provided, 

so With respect to Strictly Conforming POSIX.1 Applications, the word may means 

6i that the optional feature shall not be used. 

52 2.2.1.4 obsolescent: An indication that a certain feature may be considered for | 

53 withdrawal in future revisions of this part of ISO/IEC 9945. I 

54 Obsolescent features are retained in this version because of their widespread use. | 

55 Their use in new applications is discouraged. j 

56 2.2. 1.5 shall: An indication of a requirement on the implementation or on | 

57 Strictly Conforming POSIX.1 Applications, where appropriate. i 

58 2.2.1.6 should: j 

69 (1) With respect to implementations, an indication of an implementation | 

60 recommendation, but not a requirement. | 

61 (2) With respect to applications, an indication of a recommended program- | 

62 ming practice for applications and a requirement for Strictly Conforming 

63 POSIX.1 Applications. 
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2.2.1.7 supported: A condition regarding optional functionality. 

Certain functionality in this part of ISO/IEC 9945 is optional, but the interfaces to 
that functionality are always required. If the functionality is supported, the 
interfaces work as specified by this part of ISO/IEC 9945 (except that they do not 
return the error condition indicated for the unsupported case). If the functional- 
ity is not supported , the interface shall always return the indication specified for 
this situation. 

2.2. 1.8 system documentation: All documentation provided with an imple- 
mentation, except the conformance document. 

Electronically distributed documents for an implementation are considered part of 
the system documentation. 

2.2.1.9 undefined: An indication that this part of ISO/IEC 9945 imposes no por- 
tability requirements on an application’s use of an indeterminate value or its 
behavior with erroneous program constructs or erroneous data. 

Implementations (or other standards) may specify the result of using that value or 
causing that behavior. An application using such behaviors is using extensions, 
as defined in 1.3. 2.3. 

2.2.1.10 unspecified: An indication that this part of ISO/IEC 9945 imposes no 
portability requirements on applications for correct program constructs or correct 
data regarding a value or behavior. 

Implementations (or other standards) may specify the result of using that value or 
causing that behavior. An application requiring a specific behavior, rather than 
tolerating any behavior when using that functionality, is using extensions, as 
defined in 1.3. 2.3. 


2.2.2 General Terms ^ 

For the purposes of this part of ISO/IEC 9945, the following definitions apply: I 

2.2.2.1 absolute pathname: See pathname resolution in 2.3.6. 

2.2.2.2 access mode: A form of access permitted to a file. 

2.2.2.3 address space: The memory locations that can be referenced by a 


2. 2.2.4 appropriate privileges: An implementation-defined means of associat- 
ing privileges with a process with regard to the function calls and function call 
options defined in this part of ISO/IEC 9945 that need special privileges. 

There may be zero or more such means. 
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99 cess group. 

100 2.2.2.6 background process group: Any process group, other than a fore- j 

101 ground process group, that is a member of a session that has established a con- 

102 nection with a controlling terminal. ' 

io:> 2. 2.2.7 block special file: A file that refers to a device. 

104 A block special file is normally distinguished from a character special file by pro- 

ios viding access to the device in a manner such that the hardware characteristics of 

106 the device are not visible. 

107 2.2.2.8 character: A sequence of one or more bytes representing a single 

108 graphic symbol. 

109 NOTE: This term corresponds in the C Standard (2) to the term multibyte character, noting that a 

110 single-byte character is a special case of multibyte character. Unlike the usage in the C Standard 

111 (2), character here has no necessary relationship with storage space, and byte is used when storage 

112 space is discussed. 


113 2. 2. 2.9 character special file: A file that refers to a device. 

in One specific type of character special file is a terminal device file, whose access is 

115 defined in 7.1. Other character special files have no structure defined by this part 

116 of ISO/IEC 9945, and their use is unspecified by this part of ISO/IEC 9945. I 

in 2.2.2.10 child process: See process in 2.2.2.62. 

ns 2.2.2.11 clock tick: An interval of time. I 

11 9 A number of these occur each second. Clock ticks are one of the units that may be | 

120 used to express a value found in type clock _t . 1 

121 2.2.2.12 controlling process: The session leader that established the connec- 

122 tion to the controlling terminal. 

123 Should the terminal subsequently cease to be a controlling terminal for this ses- 

124 sion, the session leader shall cease to be the controlling process. 

125 2.2.2.13 controlling terminal: A terminal that is associated with a session. 

126 Each session may have at most one controlling terminal associated with it, and a 

127 controlling terminal is associated with exactly one session. Certain input 

128 sequences from the controlling terminal (see 7.1) cause signals to be sent to all 

129 processes in the process group associated with the controlling terminal. 

130 2.2.2.14 current working directory: See working directory in 2.2.2.89. 
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2.2.2.15 device: A computer peripheral or an object that appears to the applica- 
tion as such. 

2.2.2.16 directory: A file that contains directory entries. 

No two directory entries in the same directory shall have the same name. 

2.2.2.17 directory entry [link]: An object that associates a filename with a file. 
Several directory entries can associate names with the same file. 

2.2.2.18 dot: The filename consisting of a single dot character ( . ). 

See pathname resolution in 2.3.6. \ 

2.2.2.19 dot-dot: The filename consisting solely of two dot characters ( . . ). 

See pathname resolution in 2.3.6. 

2.2.2.20 effective group ID: An attribute of a process that is used in determ.n- 
ing various permissions, including file access permissions, described in 2.d.2. 

See group ID. This value is subject to change during the process lifetime, as 
described in 3.1.2 and 4.2.2. 

2.2.2.21 effective user ID: An attribute of a process that is used in determining 
various permissions, including file access permissions. 

See user ID. This value is subject to change during the process lifetime, as 
described in 3.1.2 and 4.2.2. 

2.2.2.22 empty directory: A directory that contains, at most, directory entnes 
for dot and dot-dot. 

2.2.2.23 empty string [null string]: A character array whose first element is a 
null character. 

2.2.2.24 Epoch: The time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coor- 
dinated Universal Time. 

See seconds since the Epoch . 

2.2.2.25 feature test macro: A #def ined symbol used to determine whether a 
particular set of features will be included from a header. 

See 2.7.1. 

2.2.2.26 FIFO special file [FIFO]: A type of file with the property that data 
written to such a file is read on a first-in-first-out basis. 


2.2 Definitions 
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| 


161 Other characteristics of FIFOs are described in 5.3.1, 6.4.1, 6.4.2, and 6.5.3. 

162 2.2.2.27 file: An object that can be written to, or read from, or both. 

163 A file has certain attributes, including access permissions and type. File types 

164 include regular file, character special file, block special file, FIFO special file, and 

165 directory. Other types of files may be defined by the implementation. 

166 2.2.2.28 file description: See open file description in 2.2.2.51. 

167 2.2.2.29 file descriptor: A per-process unique, nonnegative integer used to 

168 identify an open file for the purpose of file access. 

169 2.2.2.30 file group class: The property of a file indicating access permissions 

170 for a process related to the process’s group identification. 

ni A process is in the file group class of a file if the process is not in the file owner 

172 class and if the effective group ID or one of the supplementary group IDs of the 

173 process matches the group ID associated with the file. Other members of the class 

174 may be implementation defined. 

175 2.2.2.31 file mode: An object containing the file permission bits and other 

176 characteristics of a file, as described in 5.6.1. 

177 2.2.2.32 filename: A name consisting of 1 to (NAME_MAX) bytes used to name a 

178 file. 

179 The characters composing the name may be selected from the set of all character 

180 values excluding the slash character and the null character. The filenames dot 

181 and dot-dot have special meaning; see pathname resolution in 2.3.6. A filename is 

182 sometimes referred to as a pathname component. 

183 2.2.2.33 file offset: The byte position in the file where the next I/O operation 

184 begins. 

185 Each open file description associated with a regular file, block special file, or 

186 directory has a file offset. A character special file that does not refer to a terminal 

187 device may have a file offset. There is no file offset specified for a pipe or FIFO. 

188 2.2.2.34 file other class: The property of a file indicating access permissions for 

189 a process related to the process’s user and group identification. 

190 A process is in the file other class of a file if the process is not in the file owner 

191 class or file group class. 

192 2.2.2.35 file owner class: The property of a file indicating access permissions 

193 for a process related to the process’s user identification. 

194 A process is in the file owner class of a file if the effective user ID of the process 

195 matches the user ID of the file. 
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2.2.2.36 file permission bits: Information about a file that is used, along with 
other information, to determine if a process has read, write, or execute/search per- 
mission to a file. 

The bits are divided into three parts: owner, group, and other. Each part is used 
with the corresponding file class of processes. These bits are contained in the file 
mode, as described in 5.6.1. The detailed usage of the file permission bits in 
access decisions is described in file access permissions in 2.3.2. 

2.2.2.37 file serial number: A per-file system unique identifier for a file. 

File serial numbers are unique throughout a file system. 

2.2.2.38 file system: A collection of files and certain of their attributes. 

It provides a name space for file serial numbers referring to those files. 

2.2.2.39 foreground process: A process that is a member of a foreground pro- 
cess group. 

2.2.2.40 foreground process group: A process group whose member processes 
have certain privileges, denied to processes in background process groups, when 
accessing their controlling terminal. 

Each session that has established a connection with a controlling terminal has 
exactly one process group of the session as the foreground process group of that 
controlling terminal. See 7. 1.1. 4. 

2.2.2.41 foreground process group ID: The process group ID of the foreground 
process group. 

2.2.2.42 group ED: A nonnegative integer, which can be contained in an object of 
type gid_t y that is used to identify a group of system users. 

Each system user is a member of at least one group. When the identity of a group 
is associated with a process, a group ID value is referred to as a real group ID, an 
effective group ID, one of the (optional) supplementary group IDs, or an (optional) 
saved set-group-ID. 

2.2.2.43 job control: A facility that allows users to selectively stop (suspend) 
the execution of processes and continue (resume) their execution at a later point. 

The user typically employs this facility via the interactive interface jointly sup- 
plied by the terminal I/O driver and a command interpreter. Conforming imple- 
mentations may optionally support job control facilities; the presence of this 
option is indicated to the application at compile time or rim time by the definition 
of the LPOSDLJOB.CONTROL} symbol; see 2.9. 

2.2.2.44 link: See directory entry in 2.2.2.17. 
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231 2.2.2.45 link count: The number of directory entries that refer to a particular 

232 file. 

233 2.2.2.46 login: The unspecified activity by which a user gains access to the | 

234 system. I 

235 Each login shall be associated with exactly one login name. I 

236 2.2.2.47 login name: A user name that is associated with a login. I 

237 2.2.2.48 mode: A collection of attributes that specifies a file’s type and its access 

238 permissions. 

239 See file access permissions in 2.3.2. 

240 2.2.2.49 null string: See empty string in 2.2.2.23. 

241 2.2.2.50 open file: A file that is currently associated with a file descriptor. 

242 2.2.2.51 open file description: A record of how a process or group of processes 

243 are accessing a file. 

244 Each file descriptor shall refer to exactly one open file description, but an open file 

245 description may be referred to by more than one file descriptor. A file offset, file 

246 status (see Table 6-5), and file access modes (see Table 6-6) are attributes of an 

247 open file description. 

248 2.2.2.52 orphaned process group: A process group in which the parent of 

249 every member is either itself a member of the group or is not a member of the 

250 group’s session. 

251 2.2.2.53 parent directory: I 

252 (1) When discussing a given directory, the directory that both contains a | 

253 directory entry for the given directory and is represented by the path- | 

254 name dot-dot in the given directory. I 

255 (2) When discussing other types of files, a directory containing a directory 

256 entry for the file under discussion. 

257 This concept does not apply to dot and dot-dot. 

258 2.2.2.54 parent process: See process in 2.2.2.62. 

259 2.2.2.55 parent process ID: An attribute of a new process after it is created by | 

260 a currently active process. I 

261 The parent process ID of a process is the process ID of its creator, for the lifetime 

262 of the creator. After the creator’s lifetime has ended, the parent process ID is the 

263 process ID of an implementation-defined system process. 
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2.2.2.56 path prefix: A pathname, with an optional ending slash, that refers to 
a directory. 


2.2.2.57 pathname: A string that is used to identify a file. 

A pathname consists of, at most, (PATH_MAX) bytes, including the terminating 
null character. It has an optional beginning slash, followed by zero or more 
filenames separated by slashes. If the pathname refers to a directory, it may also 
have one or more trailing slashes. Multiple successive slashes are considered to 
be the same as one slash. A pathname that begins with two successive slashes 
may be interpreted in an implementation-defined manner, although more than 
two leading slashes shall be treated 'as a single slash. The interpretation of the 
pathname is described in 2.3.6. 


276 2.2.2.58 pathname component: See filename in 2.2.2.32. 


2.2.2.59 pipe: An object accessed by one of the pair of file descriptors created by 
the piped function. 

Once created, the file descriptors can be used to manipulate it, and it behaves 
identically to a FIFO special file when accessed in this way. It has no name in the 
file hierarchy. 


2.2.2.60 portable filename character set: The set of characters from which I 
portable filenames are constructed. 

For a filename to be portable across conforming implementations of this part of 
ISO/IEC 9945, it shall consist only of the following characters: 

abcdefghijklmnopqrstuvwxyz 

abcdefghijklmnopqrstuvwxyz 

0123456789 

The last three characters are„the period, underscore, and hyphen characters, 
respectively. The hyphen shall not be used as the first character of a portable 
filename. Upper- and lowercase letters shall retain their unique identities 
between conforming implementations. In the case of a portable pathname, the 
slash character may also be used. 


293 2.2.2.61 privilege: See appropriate privileges in 2.2.2.4 


2.2.2.62 process: An address space and single thread of control that executes 
within that address space, and its required system resources. 

A process is created by another process issuing the fork O function. The Process 
that issues forkO is known as the parent process, and the new process created by 
the forkO is known as the child process. 


2.2.2.63 process group: A collection of processes that permits the signaling of j 
related processes. 
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301 Each process in the system is a member of a process group that is identified by a 

302 process group ID. A newly created process joins the process group of its creator. 

303 2.2.2.64 process group ID: The unique identifier representing a process group | 

304 during its lifetime. I 

306 A process group ID is a positive integer that can be contained in a pidj . It shall | 

306 not be reused by the system until the process group lifetime ends. 

307 2.2.2.65 process group leader: A process whose process ID is the same as its 

308 process group ID. 

309 2.2.2.66 process group lifetime: A period of time that begins when a process 

310 group is created and ends when the last remaining process in the group leaves the 

3 11 group, due either to the end of the last process’s process lifetime or to the last | 

312 remaining process calling the setsid( ) or setpgid{ ) functions. I 

313 2.2.2.67 process ID: The unique identifier representing a process. I 

314 A process ID is a positive integer that can be contained in a pidj. A process ID | 

316 shall not be reused by the system until the process lifetime ends. In addition, if | 

316 there exists a process group whose process group ID is equal to that process ID, 

317 the process ID shall not be reused by the system until the process group lifetime | 

318 ends. A process that is not a system process shall not have a process ID of 1. 

319 2.2.2.68 process lifetime: The period of time that begins when a process is | 

320 created and ends when its process ID is returned to the system. | 

321 After a process is created with a fork() function, it is considered active. Its thread 

322 of control and address space exist until it terminates. It then enters an inactive 

323 state where certain resources may be returned to the system, although some 

324 resources, such as the process ID, are still in use. When another process executes 

326 a wait() or waitpidi) function for an inactive process, the remaining resources are 

326 returned to the system. The last resource to be returned to the system is the pro- 

327 cess ID. At this time, the lifetime of the process ends. 

328 2.2.2.69 read-only file system: A file system that has implementation-defined 

329 characteristics restricting modifications. 

330 2.2.2.70 real group ID: The attribute of a process that, at the time of process 

331 creation, identifies the group of the user who created the process. 

332 See group ID in 2.2.2.42. This value is subject to change during the process life- 

333 time, as described in 4.2.2. 

334 2.2.2.71 real user ED: The attribute of a process that, at the time of process 

335 creation, identifies the user who created the process. 

336 See user ID in 2.2.2.87. This value is subject to change during the process life- 

337 time, as described in 4.2.2. 
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2.2.2.72 regular file: A file that is a randomly accessible sequence of bytes, with 
no further structure imposed by the system. 


340 2.2.2.73 relative pathname: See pathname resolution in 2.3.6. 


2.2.2.74 root directory: A directory, associated with a process, that is used in 
pathname resolution for pathnames that begin with a slash. 


2 2 2 75 saved set-group-ID: An attribute of a process that allows some flexibil- 
ity in the assignment of the effective group ID attribute, when the saved set-user- 
ID option is implemented, as described in 3.1.2 and 4.2.2. 


2 2 2.76 saved set-user-ID: An attribute of a process that allows some flexibil- 
ity in the assignment of the effective user ID attribute, when the saved set-user-ID 
option is implemented, as described in 3.1.2 and 4.2.2. 


2.2.2.77 seconds since the Epoch: A value to be interpreted as the number of 
seconds between a specified time and the Epoch. 

A Coordinated Universal Time name (specified in terms of seconds (tm_sec), 
minutes itm_min), hours ( tmjiour ), days since January 1 of the year (tmjyday), 
and calendar year minus 1900 ( tmjyear ) is related to a time represented as 
seconds since the Epoch, according to the expression below. 

If the year < 1970 or the value is negative, the relationship is undefined. If the 
year > 1970 and the value is nonnegative, the value is related to a Coordinated 
Universal Time name according to the expression: 

tm_sec + tmjnin* 60 + tmjiour* 3600 + tmjyday*86 400 + 

(i tm _year-70)*31 536 000 + ((tm_year-69)/4)*86 400 


2.2.2.78 session: A collection of process groups established for job control 
purposes. 

Each process group is a member of a session. A process is considered to be a 
member of the session of which its process group is a member. A newly seated 
process joins the session of its creator. A process can alter its session membership 
(see 4.3.2). Implementations that support the setpgidO function (see 4.3.3) can 
have multiple process groups in the same session. 


367 2.2.2.79 session leader: A process that has created a session (see 4.3.2). 


2.2.2.80 session lifetime: The period between when a session is created and the 
end of the lifetime of all the process groups that remain as members of the 
session. 


2.2.2.81 signal: A mechanism by which a process may be notified of, or affected 
by, an event occurring in the system. 
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373 Examples of such events include hardware exceptions and specific actions by 

374 processes. The term signal is also used to refer to the event itself. 

376 2.2.2.82 slash: The literal character “/” 

376 This character is also known as solidus in ISO 8859-1 {B34}. 

377 2.2.2.83 supplementary group ID: An attribute of a process used in determin- | 

378 ing file access permissions. I 

379 A process has up to {NGROUPS_MAX} supplementary group IDs in addition to the 

380 effective group ID. The supplementary group IDs of a process are set to the sup- 

381 plementary group IDs of the parent process when the process is created. Whether 

382 a process’s effective group ID is included in or omitted from its list of supplemen- 

383 tary group IDs is unspecified. 

384 2.2.2.84 system: An implementation of this part of ISO/IEC 9945. 

386 2.2.2.85 system process: An object, other than a process executing an applica- 

386 tion, that is defined by the system and has a process ID. 

387 2.2.2.86 terminal [terminal device]: A character special file that obeys the 

388 specifications of 7.1. I 

389 2.2.2.87 user ED: A nonnegative integer, which can be contained in an object of | ; 

390 type uidjt, that is used to identify a system user. I 

391 When the identity of a user is associated with a process, a user ID value is 

392 referred to as a real user ID, an effective user ID, or an (optional) saved 

393 set-user-ID. 

394 2.2.2.88 user name: A string that is used to identify a user, as described in 9.1. I 

395 2.2.2.89 working directory [current working directory]: A directory, asso- 

396 dated with a process, that is used in pathname resolution for pathnames that do 

397 not begin with a slash. 

398 2.2.3 Abbreviations I 

399 For the purposes of this part of ISO/IEC 9945, the following abbreviations apply: | 

400 2.2.3.1 C Standard: ISO/IEC 9899, Information technology — Programming | 

401 languages — C (2). I 

402 2.2.3.2 IRV: The International Reference Version coded character set described | 

403 in ISO/IEC 646 (1). ■ j 
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404 2.2.3.3 POSIX. 1: This part of ISO/IEC 9945. 


406 2.3 General Concepts 

406 2.3.1 extended security controls: The access control (s ee file access permis- 

407 sions) and privilege (see appropriate privileges m 2.2.2A) mechanisms have been 

408 defined to allow implementation-defined extended security controls. These permit 

409 an implementation to provide security mechanisms to implement different secu- 

2 rity policies than described in this part of ISO/IEC 9945. These mechanisms shall 

411 not alter or override the defined semantics of any of the functions in this part of 

412 ISO/IEC 9945. \ 

413 2.3.2 file access permissions: The standard file access control mechanism uses 

414 the file permission bits, as described below. These bits are set at file creation y 

416 openO, creatl), mkdirQ, and mkfifoO and are changed by chmodO- These bits are 

416 read by stat( ) or fstatQ. 

417 Implementations may provide additional or alternate file access control mechan- 
ic isms, or both. An additional access control mechanism shall only further restnc 

419 the access permissions defined by the file permission bits. An alternate access 

420 control mechanism shall: 

421 (1) Specify file permission bits for the file owner class, file group class and 

422 fife other class of the file, corresponding to the access permissions, to be 

423 returned by statO or fstatO- 

424 (2) Be enabled only by explicit user action, on a per-file basis by the file 

426 owner or a user with the appropriate privilege. 

426 (3) Be disabled for a file after the file permission bits are changed for that 

427 file with ChmodO. The disabling of the alternate mechanism need not 

428 disable any additional mechanisms defined by an implementation. 

429 Whenever a process requests file access permission for ^a d "rite ° r 

430 execute/search, if no additional mechanism denies access, access is determined as 

431 follows: 

432 (1) If a process has the appropriate privilege: 

433 (a) If read, write, or directory search permission is requested, access is 

434 granted. 

435 (b) If execute permission is requested, access is granted if execute per- 

4 36 mission is granted to at least one user by the file permission bits or 

437 by an alternate access control mechanism; otherwise, access is 

438 denied. 

439 (2) Otherwise: 

440 (a) The file permission bits of a file contain read write, and 

441 execute/search permissions for the file owner class, file group class, 

442 and file other class. 

443 (b) Access is granted if an alternate access control mechanism is not j 

44 4 enabled and the requested access permission bit is set lor the class | 
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446 (file owner class, file group class, or file other class) to which the | 

446 process belongs, or if an alternate access control mechanism is | 

447 enabled and it allows the requested access; otherwise, access is 

448 denied. 

449 2.3*3 file hierarchy: Files in the system are organized in a hierarchical struc- 

460 ture in which all of the nonterminal nodes are directories and all of the terminal 

461 nodes are any other type of file. Because multiple directory entries may refer to 

462 the same file, the hierarchy is properly described as a "directed graph.” 

463 2.3.4 filename portability: Filenames should be constructed from the portable 

454 filename character set because the use of other characters can be confusing or 

466 ambiguous in certain contexts. 

456 2.3.5 file times update: Each file has three distinct associated time values: | 

457 st_atime, st_mtime, and st_ctime. The st_atime field is associated with the times | 

468 that the file data is accessed; st_mtime is associated with the times that the file | 

469 data is modified; and st_ctime is associated with the times that file status is | 

460 changed. These values are returned in the file characteristics structure, as I 

461 described in 5.6.1. 

462 Any function in this part of ISO/IEC 9945 that is required to read or write file data | 

463 or change the file status indicates which of the appropriate time-related fields are | 

464 to be "marked for update.” If an implementation of such a function marks for | 

466 update a time-related field not specified by this part of ISO/IEC 9945, this shall be | 

466 documented, except that any changes caused by pathname resolution need not be | . 

467 documented. For the other functions in this part of ISO/IEC 9945 (those that are | 

468 not explicitly required to read or write file data or change file status, but that in I 

469 some implementations happen to do so), the effect is unspecified. 

470 An implementation may update fields that are marked for update immediately or 

471 it may update such fields periodically. When the fields are updated, they are set 

472 to the current time and the update marks are cleared. All fields that are marked 

473 for update shall be updated when the file is no longer open by any process, or 

474 when a stat() or fstat( ) is performed on the file. Other times at which updates are 

475 done are unspecified. Updates are not done for files -on read-only file systems. 

476 2.3.6 pathname resolution: Pathname resolution is performed for a process to 

477 resolve a pathname to a particular file in a file hierarchy. There may be multiple 

478 pathnames that resolve to the same file. 

479 Each filename in the pathname is located in the directory specified by its prede- 

480 cessor (for example, in the pathname fragment “a/b”, file “b” is located in direc- 

481 tory “a”). Pathname resolution fails if this cannot be accomplished. If the path- 

482 name begins with a slash, the predecessor of the first filename in the pathname is 

483 taken to be the root directory of the process (such pathnames are referred to as 

484 absolute pathnames). If the pathname does not begin with a slash, the predeces- 

485 sor of the first filename of the pathname is taken to be the current working direc- 

486 tory of the process (such pathnames are referred to as “relative pathnames”). 

487 The interpretation of a pathname component is dependent on the values of 

488 (NAME_MAX) and (_POSIX_NO_TRUNC) associated with the path prefix of that 

489 component. If any pathname component is longer than (NAMEJVLAX), and 
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490 LPOSIX^NOJTRUNC) is in effect for the path prefix of that component (see 5.7.1), 

491 the implementation shall consider this an error condition. Otherwise, the imple- 

492 mentation shall use the first (NAME_MAX) bytes of the pathname component. 

493 The special filename, dot, refers to the directory specified by its predecessor. The 

494 special filename, dot-dot, refers to the parent directory of its predecessor direc- 
496 tory. As a special case, in the root directory, dot-dot may refer to the root direc- 

496 tory itself. 

497 A pathname consisting of a single slash resolves to the root directory of the pro- 

498 cess. A null pathname is invalid. 


i 499 2.4 Error Numbers 

600 Most functions provide an error number in the external variable errno, which is 

601 defined as: 

602 extern int errno; 

603 The value of this variable shall be defined only after a call to a function for which 

604 it is explicitly stated to be set and until it is changed by the next function call. 

606 The variable errno should only be examined when it is indicated to be valid by a 

606 function’s return value. No function defined in this part of ISO/IEC 9945 sets 

607 errno to zero to indicate an error. 

608 If more than one ' error occurs in processing a function call, this part of 

609 ISO/IEC 9945 does not define in what order the errors are detected; therefore, any 

610 one of the possible errors may be returned. 

611 Implementations may support additional errors not included in this clause, may | 

612 generate errors included in this clause under circumstances other than those | 

613 described in this clause, or may contain extensions or limitations that prevent | 

614 some errors from occurring. The Errors subclause in each function description | 

616 specifies which error conditions shall be detected by all implementations and | 

, 616 which may be optionally detected by an implementation. Each implementation | 

617 shall document, in the conformance document, situations in which each of the | 

618 optional conditions are detected. If no error condition is detected, the action | 

619 requested shall be successful. Implementations may contain extensions or limita- | 

620 tions that prevent some specified errors from occurring. I 

621 Implementations may generate error numbers listed in this clause under cir- | 

622 cumstances other than those described, if and only if all those error conditions can | 

623 always be treated identically to the error conditions as described in this part of | 

624 ISO/IEC 9945. Implementations may support additional errors not listed in this | 

626 clause, but shall not generate a different error number from one required by this | 

626 part of ISO/IEC 9945 for an error condition described in this part of ISO/IEC 9945. | 

627 The following symbolic names identify the possible error numbers, in the context 

628 of functions specifically defined in this part of ISO/IEC 9945; these general descrip- 

629 tions are more precisely defined in the Errors subclauses of functions that return 

530 them. Only these symbolic names should be used in programs, since the actual 

631 value of an error number is unspecified. All values listed in this clause shall be | 

632 unique. The values for these names shall be found in the header <errno.h>. 
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The actual values are unspecified by thi9 part of ISO/IEC 9945. 

[E2BIG1 Arg list too long 

The sum of the number of bytes used by the new process image’s 
argument list and environment list was greater than the system- 
imposed limit of (ARG_MAX) bytes. 

[EACCESJ Permission denied 

An attempt was made to access a file in a way forbidden by its file 
access permissions. 

I EAGAIN] Resource temporarily unavailable 

This i9 a temporary condition, and later calls to the same routine 
may complete normally. 

[EBADFl Bad file descriptor 

A file descriptor argument was out of range, referred to no open 
file, or a read (write) request was made to a file that was only 
open for writing (reading). 

[EBUSY1 Resource busy 

An attempt was made to use a system resource that was not 
available at the time because it was being used by a process in a 
manner that would have conflicted with the request being made 
by this process. 


553 [ECHILD] No child processes 


654 

565 


A wait () or waitpidO function was executed by a process that had 
no existing or unwaited-for child processes. 

556 

657 

558 

[EDEADLK] 

Resource deadlock avoided 

An attempt was made to lock a system resource that would have 
resulted in a deadlock situation. 

569 

560 

561 

[EDOM] 

Domain error 

Defined in the C Standard [2); an input argument was outside the 
defined domain of the mathematical function. 

562 

563 

564 

[EEXIST] 

File exists 

An existing file was specified in an inappropriate context; for 
instance, as the new link name in a link() function. 

665 

666 

567 

568 

569 

[EFAULTI 

Bad address 

The system detected an invalid address in attempting to use an 
argument of a call. The reliable detection of this error is imple- 
mentation defined; however, implementations that do detect this 
condition shall use this value. 

570 

571 

572 

[EFBIGI 

File too large 

The size of a file would exceed an implementation-defined max- 
imum file size. 

673 

574 

675 

576 

[EINTR] 

Interrupted function call 

An asynchronous signal (such as SIGINT or SIGQUIT; see the 
description of header <signal.h> in 3.3.1) was caught by the 
process during the execution of an interruptible function. If the 





I 


24 


2 Terminology and General Requirements 


Part 1: SYSTEM API [C LANGUAGE] 


ISO/IEC 9946-1: 1990 
IEEE Std 1003.1-1990 


signal handler performs a normal return, the interrupted func- 
tion call may return this error condition. 

[EINVAL] Invalid argument 

Some invalid argument was supplied. [For example, specifying 
an undefined signed to a signali) or kill() function). 

[EIO] Input/output error 

Some physical input or output error occurred. This error may be 
reported on a subsequent operation on the same file descriptor. 
Any other error-causing operation on the same file descriptor may 
cause the [EIO] error indication to be lost. 

[EISDIR] Is a directory v 

An attempt was made to open a directory with write mode 
specified. 

[EMFILE] Too many open files 

An attempt wa 9 made to open more than the maximum number of 
[OPEN_MAX) file descriptors allowed in this process. 

[EMLINK] Too many links 

An attempt was made to have the link count of a single file exceed 
{LINKJVIAX}. 

[ENAMETOOLONG] Filename too long 

The size of a pathname string exceeded [PATH_MAX), or a path- 
name component was longer than [NAME_MAX) and 
[_POSIX^NO_TRUNCl was in effect for that file. 

[ENFILE] Too many open files in system 

Too many files are currently open in the system. The system 
reached its predefined limit for simultaneously open files and 
temporarily could not accept requests to open another one. 

[ENODEV] No such device 

An attempt was-made to apply an inappropriate function to a dev- 
ice; for example, trying to read a wnte-only device such as a 
printer. 

[ENOENT] No such file or directory 

A component of a specified pathname did not exist, or the path- 
name was an empty string. 

[ENOEXEC] Exec format error 

A request was made to execute a file that, although it had the 
appropriate permissions, was not in the format required by the 
implementation for executable files. 

[ENOLCK] No locks available 

A system-imposed limit on the number of simultaneous file and 
record locks was reached, and no more were available at that 
time. 

[ENOMEM] Not enough space 

The new process image required more memory than was allowed 
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by the hardware or by system-imposed memory management 
constraints. 

[ENOSPC] No space left on device 

During a write () function on a regular file, or when extending a 
directory, there was no free space left on the device. 

[ENOSYS] Function not implemented 

An attempt was made to use a function that is not available in 
this implementation. 

[ENOTDIR] Not a directory 

A component of the specified pathname existed, but it was not a 
directory, when a directory was expected. 

[ENOTEMPTY] Directory not empty 

A directory with entries other than dot and dot-dot was supplied 
when an empty directory was expected. 

[ENOTTY] Inappropriate I/O control operation 

A control function was attempted for a file or a special file for 
which the operation was inappropriate. 

[ENXIO] No such device or address 

Input or output on a special file referred to a device that did not 
exist, or made a request beyond the limits of the device. This 
error may also occur when, for example, a tape drive is not online 
or a disk pack is not loaded on a drive. 

[EPERM] Operation not permitted 

An attempt was made to perform an operation limited to 
processes with appropriate privileges or to the owner of a file or 
other resource. 

[EPIPE] Broken pipe 

A write was attempted on a pipe or FIFO for which there was no 
process to read the data. 

[ERANGE] Result too large 

Defined in the C Standard {2}; the result of the function was too 
large to fit in the available space. 

[EROFS] Read-only file system 

An attempt was made to modify a file or directory on a file system 
that was read-only at that time. 

[ESPIPE] Invalid seek 

An Iseek () function was issued on a pipe or FIFO. 

[ESRCH] No such process 

No process could be found corresponding to that specified by the 
given process ID. 

[EXDEV] Improper link 

A link to a file on another file system was attempted.’ 
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2.5 Primitive System Data Types 

least the types shown in Table 2-1. 

Table 2-1 - Primitive System Data Types 

Defined Description 

Type 

deuj Used for device numberB. \ 

gidj Used for group IDs. 

'Zdej U«d for attributes, for example file type, file access permissions. 

nlinkj Used for link counts. 

off t Used for file sizes. 

pid j Used for process IDs and process group IDs. 

„• , Ah defined in the C Standard (2). . 

ssiZj Used by functions that return a count of bytes (memory space) or an error indication. 

uidj Used for user IDs. 


Sues to toe r^ge from -1 to (SSIZE.MAX1, inclusive. The types «*J and 
ssizej shall also be defined in the header <unistd . h>. 

Additional unspecified type symbols ending to J may be defined to i anj -header 
specified by POSIX.1. The visibility of such symbols need not be controlled by a y 
feature test macro other than _POSIX_SOURCE. 


2.6 Environment Description 

An array of strings called the environment is made available when a process 
tegin7 This array is pointed to by the external variable enmron, winch is defined 

as: 

extern char **environ; 

These strings have the form “name = value”-, names shall not contain the character 
, _ , There^is no meaning associated with the order of the strings in the enviro 
ment. If more than one string to a process’s environment hasthesamenam.. to 
consequences are undefined. The following names may be defined and have the 
indicated meaning if they are defined: 

HOME The name of the user’s initial working directory from the 

user database (see the description of the header <pwd . h 
in 9.2.2). 
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LC_C OLLATE 
LC_CTYPE 


LC_MONETARY 


LC_NUMERIC 


LC_TIME 


LOGNAME 


The name of the locale to use for locale categories when | 
both LC_ALL and the corresponding environment variable | 
(beginning with “LC_”) do not specify a locale. | 

The name of the locale to be used to override any values | 
for locale categories specified by the setting of LANG or | 
any environment variables beginning with “LC_”. i 

The name of the locale for collation information. 

The name of the locale for character classification. 

The name of the locale containing monetary-related 
numeric editing information. 

The name of the locale containing numeric editing (i.e., 
radix character) information. 

The name of the locale for date/time formatting 
information. 

The login name associated with the current process. The | 
value shall be composed of characters from the portable | 
filename character set. ; 

NOTE: An application that requires, or an installation that actually 
uses, characters outside the portable filename character set would not 
strictly conform to this part of ISO/IEC 9945. However, it is reasonable 
to expect that such characters would be used in many countries (recog- 
nizing the reduced level of interchange implied by this), and applica- 
tions or installations should permit such usage where possible. No 
error is defined by this part of ISO/IEC 9945 for violation of this 
condition. 


The sequence of path prefixes that certain functions apply 
in searching for an executable file known only by a 
filename (a pathname that does not contain a slash). The 
prefixes are separated by a colon ( : ). When a nonzero- 
length prefix is applied to this filename, a slash is 
inserted between the prefix and the filename. A zero- 
length prefix is a special prefix that indicates the current 
working directory. It appears as two adjacent colons ( : : ), 
as an initial colon preceding the rest of the list, or as a 
trailing colon following the rest of the list. The list is 
searched from beginning to end until an executable pro- 
gram by the specified name is found. If the pathname 
being sought contains a slash, the search through the 
path prefixes is not performed. 

The terminal type for which output is to be prepared. 
This information is used by commands and application 
programs wishing to exploit special capabilities specific to 
a terminal. 
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TZ 


Time zone information. The format of this string is 
defined in 8.1.1. 


Environment variable name 3 used or created by an application should consist 
solely of characters from the portable filename character set. Other characters 
may be permitted by an implementation; applications shall tolerate the presence 
of such names. Upper- and lowercase letters retain their unique identities and 
are not folded together. System-defined environment variable names should 
begin with a capital letter or underscore and be composed of only capital letters, 
underscores, and numbers. 


The values that the environment variables may be assigned are not restricted 
except that they are considered to end with a null byte, and the total space used 
to store the environment and the arguments to the process is limited to 
(ARG_MAX1 bytes. 


759 Other name=value pairs may be placed in the environment by manipulating the 

’ 760 environ variable or by using envp arguments when creating a process (see 3.1.2). 


761 2.7 C Language Definitions 

762 2 . 7.1 Symbols From the C Standard 

763 The following terms and symbols used in this part of ISO/IEC 9945 are defined in | 

764 the C Standard (2): NULL, byte, array of char, clockj, header, null character, 

766 string, timej . The type clockj shall be capable of representing all integer values | 

766 from zero to the number of clock ticks in 24 h. 

767 The term NULL pointer in this part of ISO/IEC 9945 is equivalent to the term null 

768 pointer used in the C Standard (2). The symbol NULL shall be declared in 

769 <unistd.h> with the same value as required by the C Standard (2), in addition 

770 to several headers already required by the C Standard {21. 

771 Additionally, the reservation of symbols that begin with an underscore applies: 

772 (1) All external identifiers that begin with an underscore are reserved. 

773 (2) All other identifiers that begin with an underscore and either an upper- 

774 case letter or another underscore are reserved. 

775 (3) If the program defines an external identifier with the same name as a 

77 6 reserved external identifier, even in a semantically equivalent form, the 

777 behavior is undefined. 

778 Certain other namespaces are reserved by the C Standard (2). These reservations 

779 apply to this part of ISO/IEC 9945 as well. Additionally, the C Standard (2 

780 requires that it be possible to include a header more than once and that a symbol 

781 may be defined in more than one header. This requirement is also made of 

782 headers for this part of ISO/IEC 9945. 


2.7 C Language Definitions 


29 




ISO/IEC 9946-1: 1990 
IEEE Std 1003.1-1990 


INFORMATION TECHNOLOGY— POSIX 


783 2.7.2 POSIX. 1 Symbols 

784 ? l ertaia symbols in this part of ISO/IEC 9945 are defined in headers. Some of I 

?! 5 could also define other symbols than those defined by this part of | 

786 ISO/IEC 9945, potentially conflicting with symbols used by the application. Also 

787 this i part of ISO/IEC 9945 defines symbols that are not permitted by other stan- I 

788 dards to appear in those headers without some control on the visibility of those 

789 symbols. 

™ f, y “ bo ! s , c i a J led future test macros are used to control the visibility of symbols 

792 n n^tr lu r.r 3 h . ead , er '., Implementa tions> future versions of this part 
21 lSO/lh p 9945, and other standards may define additional feature test macros. 

eature test macros shall be defined in the compilation of an application before an 
794 * in clude of any header where a symbol should be visible to some, but not all 
applications If the definition of the macro does not precede the #include the 

796 result 19 undefined. 

797 Feature test macros shall begin with the underscore character ( _ ). 

798 Implementations may add symbols to the headers shown in Table 2-2, provided I 

21 Tnhl To fie ? °i' tbosesy,abols the corresponding reserved prefixes in | 

801 Tah e o'o !“ p urnentatl0na may add symbols to the headers in | 

Table 2-2 that end in the string indicated as a reserved suffix as long as the 

803 ffitfoT 6 TV® V, 'i,‘L that ST 1 ° f the nam * con8idered significant by the implemen- | 

tation. This shall be in addition to any reservations made in the C Standard (2). | 

T il any i eader defined by th is Part of ISO/IEC 9945 is included, all symbols with I 

806 the suffix _t are reserved for use by the implementation, both before and after the I 

806 #include directive. 

Z KoU the l3St lnclusion of a given header, an application may use any of the sym- I 

2 -"‘it n e olT e T e K, m o T o able 2 ' 2 f ° r c itS ° Wn PUrp0SeS ’ 38 l0n S a8 ^ requirements | 

bio hinder ^ K Iah e2 ' 2 are satisfied, noting that the symbol declared in the 

8 io header may become inaccessible. , 

T revisions ' “s part of ISO/IEC 9945, and other POSIX standards,' are | 

812 likely to use symbols m these same reserved spaces. ‘ 

2 may 3dd members t0 a structure or union without | 

8 5 Ter rflfl T* V1Slb ‘ y tb03e members with a feature test macro, as long as a | 

8 6 inZmreiT “TT the Same name caanot iat erfere with the correct 

816 interpretation of the program 

s, l 8 <f0nt i - , h> T y COntain the foll °wing symbols in addition to those | 

sis specifically required elsewhere in POSIX.1: 

SIS SEEK_CUR S.IRUSR S.ISCHR S ISREG S IWUSR I 

820 SEEK_END S.IRWXG S.ISDIR SJSUID SKGRP 

821 SEEK_SET S_IRWXO S.ISFIFO S.IWGRP S~IXOTH 

822 S_IRGRP SJRWXU SJSGID S IWOTH S IXUSR I 

823 SJROTH S.ISBLK " " 1 

2 ^ additi0n ' “„ implement ation may define the symbols “cuserid” in <unistd . h> I 
826 and L_cusend in <stdio . h>. 

. 
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OT 2 The exact meaning of feature test macros depends on the type of C language sup- 
S 73 port chosen: C Standard Language-Dependent Support and Common-Usage- I 

874 Dependent Support, described in the following two subclauses. 

875 2.7.2.J C Standard Language-Dependent Support 

lit r [ tbere f re n0 | feature test macros present in a program, the implementation I 
LI p'S 6 ° n y th ° Se ldentifiers specified as reserved identifiers in the | 

IZ 0,4 t ard () u P erm,ttm e the reservation of symbols and namespace defined in 
" “ ^ or each feature test macro present, only the symbols specified by that 

sso feature test macro plus those of the C Standard ( 2 ) shall be defined when a header 
8 «i is included. 

882 2.7.2.2 Common-Usage-Dependent Support 

“ 3 If th , e J ea ‘T > maC ™ - p OSIX_SOURCE is not defined in a program, the set of 

8«5 ISO/IEC 9^945 1 ^unspecifie'd. ader ** bey ° n<1 the requiremen ‘ 3 <* **. part of | 

2 Ln P S S f 0U T r def ' n ] ed J lx ‘ f0re any header is “eluded, no symbols other 

21 defined f^ tfi 0 ” ^ndard (2) a “ d those made " sible b 7 feature test macros 

888 defined for the program (including _POSIX_SOURCE) will be visible. Symbols from I 

889 the namespace reserved for the implementation, as defined by the C Standard (2), ; 

89 i this 8180 Permltted - The symbols beginning with two underscores are examples of | 

21 undcfined" S ° URCE ' S n<>t defined bef ° re any header * S included - the behavior is 


894 2.7.3 Headers and Function Prototypes 

896 Implementations claiming C Standard {2) Language-Dependent Support shall 
89« declare function prototypes for all functions. 

21 !)T,ii em ?u tati0n n " laim i ng Common-Usage C Language-Dependent Support shall 
s declare the result type for all functions not returning a “plain" int. 

Z sTwheThl 0119 deS ^ bed in tbe C u standard W “ d included by reference in Section 
( hether or not they are further described in this part of ISO/IEC 9945), these 

902 aZm fifth required) shall appear in the headers defined for 

903 nrototvrv! he C , Standard (2) , ^° r other functions in this part of ISO/IEC 9945, the 

™ 3ha11 a PP ear in the headers listed below. If a function 

905 is nnfrf a y K^ S P a t rt i? f n S ? /IEC " 45, is not de9cribed in the C Standard ( 2 ), and 

906 ^uniVid h ^ 6 T- l Sba bave lts prototy Pe or declaration (if required) appear in 

907 function d T’ wblch .f hal ‘ b ® nclude-ed by the application before using any 

908 for*that fnnct^ tJ ’ whether or not [t is mentioned in the Synopsis subclause 

909 be h^ ^ requirements about tbe visibility of symbols in 2.7.2 shall 
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910 

911 


913 

914 

916 

916 

917 

918 

919 

920 

921 

922 

923 
, 924 

926 

926 

927 

928 

929 

930 

931 

932 

933 

934 
936 

936 

937 

938 

939 


<dirent . h> 

opendiri ), readdirl , ), rewinddirf . ), closediri ) 

<f cntl . h> 

openO, creatO, fcntlO 

<grp . h> 

getgrguU ), getgrnam ( ) 

<pwd. h> 

getpwuidO, getpwnamO 

<set jmp . h> 

sigsetjmpO, siglongjmpO 

<signal . h> 

kill (), sigemptysetO, sigfillsetO, sigaddsetO, sigdelseti), 
sigismemberO, sigactionO, sigprocmaskl), sigpendingO, 
sigsuspendO 

<stdio . h> 

ctermidO, filenoO, fdopen ( ) 

<sys/stat .h> 

umask 0 , mkdirO, mkfifoi), stat(), fstatl), chmodO 

<sys/times . h> 

timesO 

<sys/utsname . h> 

unamel) 

<sys/wait .h> 

waitO, waitpidO 

<termios.h> 

cfgetospeedO, cfsetospeedO, cfgetispcedO, cfsetispeedO, 
tcgetattrO, tcsetattrO, tcsendbreakO, tcdrainO, 
tcflushO, tcflowl) 

<time.h> 

time 0 , tzset () 

<utime.h> 

utimeO 


The declarations in the headers shall follow the proper form for the C language 
option chosen by the implementation. Additionally, pointer arguments that refer 
to objects not modified by the function being described are declared with const 
qualifying the type to which it points. Implementations claiming Common-Usage 
C conformance to this part of ISO/IEC 9945 may ignore the presence of this key- 
word and need not include it in any function declarations. Implementations 
claiming conformance using the C Standard (2) shall use the const modifier as 
indicated in the prototypes they-ptovide. 

Implementations claiming conformance using Common-Usage C may use 
equivalent implementation-defined constructs when void is used as a result type 
for a function prototype. They may also use int when a function result is declared 
ssizejt. 


940 Neither the names of the formal parameters nor their types, as they appear in an 

941 implementation, are specified by this part of ISO/IEC 9945. The names are used 

942 within this part of ISO/IEC 9945 as a notational mechanism. However, any 

943 declaration provided by an implementation shall accept all actual parameter 

944 types that a declaration lexically identical to one in this part of ISO/IEC 9945 shall 

946 accept, including the effects of both type conversion and checking for the number 

946 of arguments implied by the presence of a filled-out prototype. The 

947 implementation’s declaration shall not cause a syntax error if an application pro- 

948 vides a prototype lexically identical to one in this part of ISO/IEC 9945. It is not a 

949 requirement that nonconforming parameters to functions that may be used by an 

960 application be diagnosed by an implementation, except as specifically required by 

961 this part of ISO/IEC 9945 or the C Standard {2}, as applicable. Where the 
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952 C Standard (2) has a more restrictive requirement for a function defined by that 

953 standard, that requirement shall be honored, and this exception does not apply. 


2.8 Numerical Limits 

The following subclauses list magnitude limitations imposed by a specific imple- 
mentation. The braces notation, (LIMIT), is used in this part of ISO/IEC 9945 to 
indicate these values, but the braces are not part of the name. 

2.8.1 C Language Limits 

The following limits used in this part of ISO/IEC 9945 are defined in the 
C Standard (2): (CHAR_BIT), (CHAR_MAX), (CHARJMIN), (INT_MAX), (INT_MIN), 
(LONGJUAX), (LONG_MIN), (MB_LEN_MAX), (SCHAR_MAX), (SCHAR_MIN), 
(SHRT_MAX), (SHRT_MIN), (UCHAR_MAX), (UINT_MAX), (ULONG_MAX), 
(USHRT_MAX). 

2.8.2 Minimum Values 

The symbols in Table 2-3 shall be defined in <limits . h> with the values shown. 
These are symbolic names for the most restrictive value for certain features on a 
system conforming to this part of ISO/IEC 9945. Related symbols are defined else- 
where in this part of ISO/IEC 9945, which reflect the actual implementation and 
which need not be as restrictive. A conforming implementation shall provide 
values at least this large. A portable application shall not require a larger value 
for correct operation. 


2.8.3 Run-Time Increasable Values 

The magnitude limitations in Table 2-4 shall be fixed by specific implementations. 

A Strictly Conforming POSIX.1 Application shall assume that the value supplied 
by <limits . h> in a specific implementation is the minimum value that pertains 
whenever the Strictly Conforming POSIX.1 Application is run under that imple- 
mentation. * A specific instance of a specific implementation may increase the 
value relative to that supplied by <limits.h> for that implementation. The 
actual value supported by a specific instance shall be provided by the sysconf X) 
function. 


3) In a future revision of this part of ISO/EEC 9945, omitting a symbol defined in this subclause from 
dimits -h> is expected to indicate that the value is variable. 
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1023 Table 2-5 - Run-Time Invariant Values (Possibly Indeterminate) 


1025 

Name 

Description 

Minimum Value 

1026 

1027 

1028 

(ARG_MAX) 

Maximum length of arguments for the exec 
functions, in bytes, including environment 
data. 

LPOSDCARG_MAX) 

1029 

1030 

(CHILD_MAX] 

Maximum number of simultaneous 
processes per real user ID. 

(_POSDCCHILD_MAX) 

1031 

1032 

(OPEN_MAX) 

Maximum number of files that one process 
can have open at any given time. 

(_POSIX_OPEN_MAX) 

1033 

1034 

1035 

1036 

(STREAM_MAX) 

The number of streams that one process 
can have open at one time. If defined, it 
shall have the same value as 
(FOPEN_MAX) from the C Standard (2). 

LPOSIX_STKEAM_MAX) 

1037 

1038 

1039 

1040 

{TZNAME_MAX> 

The maximum number of bytes supported 
for the name of a time zone (not of the TZ 
variable). 

LPOSDC_T2NAME_MAX] 


1041 2.8.5 Pathname Variable Values 

1042 The values in Table 2-6 may be constants within an implementation or may vary 

1043 from one pathname to another. 


104 ' 1 Table 2-6 - Pathname Variable Values 

1045 . 


1046 

Name 

Description 

Minimum Value 

1047 

(LINK_MAX) 

Maximum value of a file’s link count. 

LP0SIX.LINK MAX) 

1048 

1049 

(MAX_CANON) 

Maximum number of bytes in a terminal 
canonical input line. (See 7.1. 1.6.) 

(_P0SDC_MAX_CAN0N) 

1050 

1061 

1052 

1063 

1054 

(MAXJNPUT) 

Minimum number of bytes for which space 
will be available in a terminal input 
queue; therefore, the maximum number of 
bytes a portable application may require to 
be typed as input before reading them. 

Lposk_maxjnput) 

1056 

1056 

1057 

(NAME_MAX) 

Maximum number of bytes in a file name 
(not a string length; count excludes a ter- 
minating null). 

(_POSDC_NAME_MAX) 

1058 

1059 

1060 

(PATH_MAX) 

Maximum number of bytes in a pathname 
(not a string length; count excludes a ter- 
minating null). 

Lposix_path_max) 

1061 

1062 

1063 

(PBPE_BUF) 

Maximum number of bytes that can be 
written atomically when writing to a pipe. 

(_posix_pipe_buf) 


1064 For example, file systems or directories may have different characteristics. 

1066 A definition of one of the values from Table 2-6 shall be omitted from 

1066 <limits.h> on specific implementations where the corresponding -value is equal 

1067 to or greater than the stated minimum, but where the value can vary depending 


1068 

1069 


on the file to which it is applied. The actual value supported for a specific path- 
name shall be provided by the pathconfX ) function. 


1070 2 . 8.6 Invariant Values * 

1071 The value in Table 2-7 shall not vary in a given implementation. The value in | 


1072 

that table shall appear in climits . h>. 


1073 

1074 

1075 


Table 2-7 - Invariant Value 


Name 

Description 

Value 

1076 

1077 

1078 

(SSIZE_MAXj 

The maximum value that can be stored in an 
object of type ssizej. 

LPOSIX_SSIZE_MAX) 


1079 2.9 Symbolic Constants 

1080 A conforming implementation shall have the header <unistd.h>. This header 
lost defines the symbolic constants and structures referenced elsewhere in this part of 

1082 ISO/IEC 9945 . The constants defined by this header are shown in the following 

1083 subclauses. The actual values of the constants are implementation defined. 

1084 2.9.1 Symbolic Constants for the access 0 Function 

loss The constants used by the accessO function are shown in Table 2 - 8 . The con- 

1086 stants F_OK, R_OK, W_OK, and X_OK, and the expressions 

1087 R_OK | W_0K 

1088 (where the | represents the bitwise inclusive OR operator), 

1089 R_0K 1 X_OK 

1090 and 

1091 R_OK | W_OK | X_OK 

1092 shall all have distinct values. 

1093 2.9.2 Symbolic Constant for the Iseek ( ) Function 

1094 The constants used by the Iseek () function are shown in Table 2 - 9 . 
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Table 2-8 - Symbolic Constants for the access () Function 

Constant Description 

R_OK Test for read permission. 

W_OK Test for write permission. 

X^OK Test for execute or search permission. 

F_OK Test for existence of file. 

- 


1103 

1104 
1106 

1106 

1107 

1108 
1109 


lno 2.9.3 Compile-Time Symbolic Constants for Portability Specifications 

mi The constants in Table 2-10 may be used by the application, at compile time, to 

1112 determine which optional facilities are present and what actions shall be taken by 

1113 the implementation. 

I 


1124 Although a Strictly Conforming P0SIX.1 Application can rely on the values corn- 
1126 piled from the <unistd . h> header to afford it portability on all instances of an 

1126 implementation, it may choose to interrogate a value at run-time to take advan- 

1127 tage of the current configuration. See 4.8.1. 

1128 2 . 9.4 Execution-Time Symbolic Constants for Portability Specifications 

U29 The constants in Table 2-11 may be used by the application, at execution time, to 

1130 determine which optional facilities are present and what actions shall be taken by 

1131 the implementation in some circumstances described by this part of ISO/IEC 9945 
H32 as implementation defined . 


Table 2-10 — Compile-Time Symbolic Constants 


1117 LPOSIX_JOB_CONTROL} 

1118 

1119 LPOSK_SAVED_IDS) 

1120 

1121 LPOSDC_VERSION) 

1122 


Description 

If this symbol is defined, it indicates that the implementation sup- 
ports job control. 

If defined, each process has a saved set-user-ID and a saved set- 
group-ED. 

The integer value 199009L. This value shall be used for systems 
that conform to this part of ISO/IEC 9945. 


Table 2-9 - Symbolic Constants for the IseekO Function 

Constant Descripti on 

SEEK_SET Set file ofTset to offset. 

SEEK_CUR Set file offset to current plus offset. 

SEEK_END Set file offset to EOF plus offset. 


1096 

1096 

1097 

1098 

1099 

1100 
1101 
1102 
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Section 3: Process Primitives 


The functions described in this section perform the most primitive operating sys- 
tem services dealing with processes, interprocess signals, and timers. All attri- 
butes of a process that are specified, in this part of ISO/IEC 9945 shall remain 
unchanged by a process primitive unless the description of that process primitive 
states explicitly that the attribute is changed. 


e 3.1 Process Creation and Execution 


7 3.1.1 Process Creation 

8 Function: fork() 

9 3 . 1 . 1.1 Synopsis - 

10 #include <sys /types .h> 

11 pid_t fork (void); 

12 3. 1.1. 2 Description 

13 The fork () function creates a new process. The new process (child process) shall 

14 be an exact copy of the calling process (parent process) except for the following: 

is ( 1 ) The child process has a unique process ID. The child process ID also does 

16 not match any active process group ID. 

17 ( 2 ) The child process has a different parent process ID (which is the process 

18 ID of the parent process). 

19 ( 3 ) The child process has its own copy of the parent’s file descriptors. Each 

20 of the child’s file descriptors refers to the same open file description with 

21 the corresponding file descriptor of the parent. 

22 ( 4 ) The child process has its own copy of the parent’s open directory streams 

23 (see 5 . 1 . 2 ). Each open directory stream in the child process may share 

24 directory stream positioning with the corresponding directory stream of 

25 the parent. 

26 ( 5 ) The child process’s values of tms_utiine, tms_stime , tms_cutime t and 

27 tmsjcstime are set to zero (see 4 . 5 . 2 ). 
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(6) File locks previously set by the parent are not inherited by the child. 
(See 6.5.2.) 

(7) Pending alarms are cleared for the child process. (See 3.4.1.) 

(8) The set of signals pending for the child process is initialized to the empty 
set. (See 3.3.1.) 

All other process characteristics defined by this part of ISO/IEC 9945 shall be the 
same in the parent and the child processes. The inheritance of process charac- 
teristics not defined by this part of ISO/IEC 9945 is unspecified by this part of 
ISO/IEC 9945, but should be documented in the system documentation. 

After forkO , both the parent and the child processes shall be capable of executing 
independently before either terminates. 

3. 1.1.3 Returns 

Upon successful completion, fork () shall return a value of zero to the child process 
and shall return the process ID of the child process to the parent process. Both 
processes shall continue to execute from the fork ( ) function. Otherwise, a value of 
-1 shall be returned to the parent process, no child process shall be created, and 
errno shall be set to indicate the error. 


46 3. 1.1.4 Errors 

46 If any of the following conditions occur, the forkO function shall return -1 and set 

47 errno to the corresponding value: 

48 [EAGAIN] The system lacked the necessary resources to create another 

49 process, or the system-imposed limit on the total number of 

60 processes under execution by a single user would be exceeded. 

61 For each of the following conditions, if the condition is detected, the fork{) func- 

62 tion shall return —1 and set errno to the corresponding value: 

63 [ENOMEM] The process requires more space than the system is able to 

54 supply. 

66 3. 1.1. 5 Cross-References 

66 alarmO, 3.4.1; exec, 3.1.2; ficntlO, 6.5.2; kill(), 3.3.2; timesO, 4.5.2; wait, 3.2.1. 


67 3.1.2 Execute a File 

68 Functions: execl ( ), execvO, execle ( ), execveO, execlpO, execvpi). 

69 3.1.2.1 Synopsis 

60 int execl (const char *path, const char *arg, . . .); 

61 int execv (const char *path, char ‘const argv [ ] ) ; 
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62 

63 

64 
66 

66 

67 

68 

69 

70 

71 

72 

73 

74 
76 

76 

77 

78 

79 

80 
81 

82 

83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 
96 

96 

97 

98 

99 

100 
101 
102 
103 


int execle (const char *path, const char *arg, . . .); 

int execve (const char *path, char ‘const argv [ ] , char ‘const envp 13); 
int execlp (const char *file, const char *arg, . . .); 
int execvp (const char *fHe, char ‘const argv [ ]); 

3. 1.2.2 Description 

The exec family of functions shall replace the current process image with a new 
process image. The new image is constructed from a regular, executable file 
called the new process image file . There shall be no return from a successful exec 
because the calling process image is overlaid by the new process image. 

When a C program is executed a9 a result of this call, it shall be entered as a C 
language function call as follows: 

int main (int argc, char *argv [ ) ) ; 

where argc is the argument count and argv is an array of character pointers to 
the arguments themselves. In addition, the following variable: 

extern char **environ; 

is initialized as a pointer to an array of character pointers to the environment 
strings. The argv and environ arrays are each terminated by a NULL pointer. 
The NULL pointer terminating the argv array is not counted in argc. 

The arguments specified by a program with one of the exec functions shall be 
passed on to the new process image in the corresponding main () arguments. 

The argument path points to a pathname that identifies the new process image 
file. 

The argument file is used to construct a pathname that identifies the new process 
image file. If the file argument contains a slash character, the file argument shall 
be used as the pathname for this file. Otherwise, the path prefix for this fil e is 
obtained by a search of the directories passed as the environment variable PATH 
(see 2.6). If this environment variable is not present, the results of the search are 
implementation defined. 


The argument argv is an array of character pointers to null-terminated strings. 
The last member of this array shall be a NULL pointer. These strings constitute 
the argument list available to the new process image. The value in argv [0] should 
point to a filename that is associated with the process being started by one of the 
exec functions. 

The const char *arg and subsequent ellipses in the execlO, execlpO , and exe- 
cle 0 functions can be thought of as argO, argl , . . . , argn. Together they describe 
a list of one or more pointers to null-terminated character strings that represent 
the argument list available to the new program. The first argument should point 
to a filename that is associated with the process being started by one of the exec 
functions, and the last argument shall be a NULL pointer. For the execle () func- 
tion, the environment is provided by following the NULL pointer that shall ter- 
minate the list of arguments in the parameter list to execle () with an additional 
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104 parameter, as if it were declared as 

105 char ♦const envp [ ] 

106 The argument envp to execve () and the final argument to execleO name an array 

107 of character pointers to null-terminated strings. These strings constitute the 
loa environment for the new process image. The environment array is terminated by 

109 a NULL pointer. 

110 For those forms not containing an envp pointer [execlO, execv{), execlpO, and 
in execvp ()], the environment for the new process image is taken from the external 

112 variable environ in the calling process. 

113 The number of bytes available for the new process’s combined argument and 

114 environment lists is (ARG_MAX). The implementation shall specify in the system 
ns documentation (see 1.3. 1.2) whether any combination of null terminators, 
116 pointers, or alignment bytes are included in this total. 

in File descriptors open in the calling process image remain open in the new process 
lie image, except for those whose close-on-exec flag FD_CLOEXEC is set (see 6.5.2 and 

119 6.5.1). For those file descriptors that remain open, all attributes of the open file 

120 description, including file locks (see 6.5.2), remain unchanged by this function 

121 call. 

122 Directory streams open in the calling process image shall be closed in the new 

123 process image. 

124 Signals set to the default action (SIG_DFL) in the calling process image shall be 

125 set to the default action in the new process image. Signals set to be ignored 

126 (SIG_IGN) by the calling process image shall be set to be ignored by the new pro- 

127 cess image. Signals set to be caught by the calling process image shall be set to 

128 the default action in the new process image (see 3.3.1). 

129 If the set-user-ID mode bit of the new process image file is set (see 5.6.4), the effec- 

130 tive user ID of the new process image is set to the owner ID of the new process 
ini image file. Similarly, if the set-group-ID mode bit of the new process image file is 

132 set, the effective group ID of the new process image is set to the group ID of the 

133 new process image file. The real user ID, real group ID, and supplementary group 

134 IDs of the new process image remain the same as those of the calling process 
136 image. If {_POSIX_SAVED_IDS} is defined, the effective user ID and effective 

136 group ID of the new process image shall be saved (as the saved set-user-ID and the 

137 saved set-group-ID ) for use by the setuid() function. 

138 The new process image also inherits the following attributes from the calling pro- 

139 cess image: 

140 (1) Process ID 

141 (2) Parent process ID 

142 (3) Process group ID 

143 (4) Session membership 

144 (5) Real user ID 

145 (6) Real group ID 
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(7) Supplementary group IDs 

(8) Time left until an alarm clock signal (see 3.4.1) 

(9) Current working directory 

(10) Root directory 

(11) File mode creation mask (see 5.3.3) 

(12) Process signal mask (see 3.3.5) 

(13) Pending signals (see 3.3.6) 

(14) tms_utime, tms_stime, tmsjcutime , and tmsjcstime (see 4.5.2) 

All process attributes defined by this part of ISO/IEC 9945 and not specified in this 
subclause (3.1.2) shall be the same in the new and old process images. The inher- 
itance of process characteristics not defined by this part of ISO/IEC 9945 is | 
unspecified by this part of ISO/IEC 9945, but should be documented in the system | 
documentation. I 

Upon successful completion, the exec functions shall mark for update the st_atime 
field of the file. If the exec function failed, but was able to locate the process image 
file, whether the st_atime field is marked for update is unspecified. Should the 
exec function succeed, the process image file shall be considered to have been 
open()-ed. The corresponding close () shall be considered to occur at a time after 
this open, but before process termination or successful completion of a subsequent 
call to one of the exec- functions. 

The argv[] and envp[] arrays of pointers and the strings to which those arrays | 
point shall not be modified by a call to one of the exec functions, except as a conse- | 
quence of replacing the process image. I 

3.1.2.3 Returns 

If one of the exec functions returns to the calling process image, an error has 
occurred; the return value shall -be —1, and errno shall be set to indicate the error. 

3.1.2.4 Errors 

If any of the following conditions occur, the exec functions shall return —1 and set 
errno to the corresponding value: 

[E2BIG] The number of bytes used by the argument list and the environ- 
ment list of the new process image is greater than the system- 
imposed limit of (ARGJMAX) bytes. 

[EACCES] Search permission is denied for a directory listed in the path 
prefix of the new process image file, or the new process image 
file denies execution permission, or the new process image file 
is not a regular file and the implementation does not support 
execution of files of its type. 

[ENAMETOOLONG] 

The length of the path or file arguments, or an element of the 
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185 environment variable PATH prefixed to a file, exceeds 

186 (PATH_MAX), or a pathname component is longer than 

187 (NAME_MAX) and (_POSIX_NO_TRUNC) is in effect for that file. 

18 a [ENOENT] One or more components of the pathname of the new process 

189 image file do not exist, or the path or file argument points to an 

190 empty string. 

191 [ENOTDIR] A component of the path prefix of the new process image file is 

192 not a directory. 

193 If any of the following conditions occur, the execlO, execuO, execle (), and execvef) 

194 functions shall return —1 and set errno to the corresponding value: 

196 [ENOEXEC] The new process image file has the appropriate access permis- 

196 sion, but is not in the proper format. 

197 For each of the following conditions, if the condition is detected, the exec functions 

198 shall return -1 and return the corresponding value in errno : 

199 [ENOMEM] The new process image requires more memory than is allowed 

200 b Y the hardware or system-imposed memory management con- 

201 straints. 

202 3. 1.2.5 Cross-References 

203 alarmi), 3.4.1; chmodO, 5.6.4; _exit(), 3.2.2; fcntlO, 6.5.2; forkO, 3 . 1 . 1 ; setuidO, 

204 4.2.2; <signal . h>, 3.3.1; sigprocmask (), 3.3.5; sigpendingO, 3.3.6; stat ( ), 5.6.2; 

205 <sys/ stat . h>, 5.6.1; times (), 4.5.2; umask (), 5.3.3; 2.6. 


206 3.2 Process Termination 

207 There are two kinds of process termination: 

208 (1) Normal termination occurs by a return from mainO or when requested 

209 with the exit ( ) or _exit( ) functions. 

210 (2) Abnormal termination occurs when requested by the abortO function or 

211 when some signals are received (see 3.3.1). 

212 The exitO and abort( ) functions shall be as described in the C Standard (2). Both | 

213 o*oo and abort< ‘ ) sha11 terminate a process with the consequences specified in 

214 3.2.2, except that the status made available to wait() or waitpidO by abortO shall 

216 be that of a process terminated by the SIGABRT signal. 

21 G A parent process can suspend its execution to wait for termination of a child pro- 

217 cess with the wait( ) or waitpidO functions. 
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3.2.1 Wait for Process Termination 

Functions: waitO, waitpidO 


3.2.1.1 Synopsis 

♦include <sys/types .h> 

♦include <sys/wait.h> 

pid_t wait(int *stat_loc) ; 

pid_t. waitpid (pid_t pid, int +stat_loc, int options ); 

\ 

3.2.1.2 Description 

The waitO and waitpidO functions allow the calling process to obtain status infor- 
mation pertaining to one of its child processes. Various options permit status 
information to be obtained for child processes that have terminated or stopped. If 
status information is available for two or more child processes, the order in which 
their status is reported is unspecified. 

The waitO function shall suspend execution of the calling process until status 
information for one of its terminated child processes is available, or until a signal 
whose action is either to execute a signal-catching function or to terminate the 
process is delivered. If status information is available prior to the call to waitO, 
return shall be immediate. 

The waitpidO function shall behave identically to the waitO function if the pid 
argument has a value of -1 and the options argument has a value of zero. Other- 
wise, its behavior shall be modified by the values of the pid and options 
arguments. 

The pid argument specifies a set of child processes for which status is requested. 
The waitpidO function shall only return the status of a child process from this 
set. 

(1) If pid is equal to -1, status is requested for any child process. In this 
respect, waitpidO is then equivalent to waitO . 

(2) If pid is greater than zero, it specifies the process ID of a single child pro- 
cess for which status is requested. 

(3) If pid is equal to zero, status is requested for any child process whose 
process group ID is equal to that of the calling process. 

(4) If pid is less than -1, status is requested for any child process whose pro- 
cess group ID is equal to the absolute value of pid. 

The options argument is constructed from the bitwise inclusive OR of zero or more 
of the following flags, defined in the header <sys/wait . h>: 

WNOHANG The waitpidO function shall not suspend execution of the cal- 
ling process if status is not immediately available for one of the 
child processes specified by pid. 

WUNTRACED If the implementation supports job control, the status of any 
child processes specified by pid that are stopped, and whose 
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status has not yet been reported since they stopped, shall also 
be reported to the requesting process. 

If wait () or waitpidi) return because the status of a child process is available, 
these functions shall return a value equal to the process ID of the child process. 
In this case, if the value of the argument statjoc is not NULL, information shall 
be stored in the location pointed to by statjoc. If and only if the status returned 
is from a terminated child process that returned a value of zero from main () or 
passed a value of zero as the status argument to _exit() or cxit(), the value stored 
at the location pointed to by statjoc shall be zero. Regardless of its value, this 
information may be interpreted using the following macros, which are defined in 
<sys/wait . h> and evaluate to integral expressions; the statjual argument is the 
integer value pointed to by statjoc. 

WIFEXITED(stat_uaI) 

This macro evaluates to a nonzero value if status was returned 
for a child process that terminated normally. 

WEXITSTATUS(sta<_uaZ ) 

If the value of WIFEXITED(sfat_oa/ ) is nonzero, this macro 
evaluates to the low-order 8 bits of the status argument that 
the child process passed to _exitO or exit(), or the value the 
child process returned from main(). 

WIFSIGNALED(s<af_uaI ) 

This macro evaluates to a nonzero value if status was returned 
for a child process that terminated due to the receipt of a signal 
that was not caught (see 3 . 3 . 1 ). 

WTERMSIGKstat_uaI) 

If the value of WIFSIGNALED(siaf_ua/) is nonzero, this macro 
evaluates to the number of the signal that caused the termina- 
tion of the child process. 

WIFSTOPPED(sfa<_uaI ) 

This macro evaluates to a nonzero value if status was returned 
for a child process that is currently stopped. 

WSTOPSIG(stat_val ) 

If the value of WIFSTOPPED(stat_ua/) is nonzero, this macro 
evaluates to the number of the signal that caused the child pro- 
cess to stop. 

If the information stored at the location pointed to by statjoc was stored there by 
a call to the waitpidi. ) function that specified the WUNTRACED flag, exactly 
one of the macros WIFEXITEDf •statjoc), WIFSIGNALED i*statJoc), or 
WIFSTOPPED(*stof Joe) shall evaluate to a nonzero value. If the information 
stored at the location pointed to by statjoc was stored there by a call to the wait- 
pidi) function that did not specify the WUNTRACED flag or by a call to the 
waiti) function, exactly one of the macros WIFEXITEDJstatJoc) or 
WIFSIGNALED( *stat Joe) shall evaluate to a nonzero value. 
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301 An implementation may define additional circumstances under which waiti) or 

302 waitpidi) reports status. This shall not occur unless the calling process or one of 

303 its child processes explicitly makes use of a nonstandard extension. In these 

304 cases, the interpretation of the reported status is implementation defined. 

305 

306 3.2. 1.3 Returns 

307 If the waiti) or waitpidi) functions return because the status of a child process is 

308 available, these functions shall return a value equal to the process ID of the child 

309 process for which status is reported. 'Jf the waiti) or waitpidi) functions return 

310 due to the delivery of a signal to the calling process, a value of -1 shall be 

311 returned and errno shall be set to [EINTR]. If the waitpidi) function was invoked 

312 with WNOHANG set in options , has at least one child process specified by pid for 

313 which status is not available, and status is not available for any process specified 

314 by pid, a value of zero shall be returned. Otherwise, a value of —1 shall be 

316 returned, and errno shall be set to indicate the error. 

316 3.2.1.4 Errors 

317 If any of the following conditions occur, the waiti ) function shall return -1 and set 

318 errno to the corresponding value: 

319 [ECHILD] The calling process has no existing unwaited-for child 

320 processes. £ 

321 [EINTRl The function was interrupted by a signal. The value of the 

322 location pointed to by statjoc is undefined. 

323 If any of the following conditions occur, the waitpidi) function shall return —1 and 

324 set errno to the corresponding value: 

326 [ECHILD] The process or process group specified by pid does not exist or 

326 is not a child Of the calling process. 

327 [EINTR] The function was interrupted by a signal. The value of the 

328 location pointed to by statjoc is undefined. 

329 [EINVAL] The value of the options argument is not valid. 

330 3.2.1.5 Cross-References 

331 jexiti), 3.2.2; forki), 3.1.1; pausei), 3.4.2; timesi), 4.5.2; <signal . h>, 3.3.1. 

332 3.2.2 Terminate a Process 

333 Function: _exiti) 
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334 3.2.2.1 Synopsis 

335 void _exit(int status ); 

336 3.2.2.2 Description 

337 The _exit() function shall terminate the calling process with the following 

338 consequences: 

339 (1) AM open file descriptors and directory streams in the calling process are 

340 closed. 

341 (2) If the parent process of the calling process is executing a wait() or wait- 

342 pid(), it is notified of the termination of the calling process and the low 

343 order 8 bits of status are made available to it; see 3.2.1. 

344 (3) If the parent process of the calling process is not executing a waitO or 

343 waitpidi) function, the exit status code is saved for return to the parent 

346 process whenever the parent process executes an appropriate subsequent 

347 waitO or waitpidi,). 

348 (4) Termination of a process does not directly terminate its children. The 

349 sending of a SIGHUP signal as described below indirectly terminates chil- 

350 dren in some circumstances. Children of a terminated process shall be 

351 assigned a new parent process ID, corresponding to an implementation- 

352 defined system process. 

353 (5) If the implementation supports the SIGCHLD signal, a SIGCHLD signal 

354 shall be sent to the parent process. 

355 (6) If the process is a controlling process, the SIGHUP signal shall be sent to 

366 each process in the foreground process group of the controlling terminal 

357 belonging to the calling process. 

358 (7) If the process is a controlling process, the controlling terminal associated 

359 with the session is disassociated from the session, allowing it to be 

360 acquired by a new controlling process. 

361 (8) If the implementation supports job control, and if the exit of the process 

362 causes a process group to become orphaned, and if any member of the 

363 newl y orphaned process group is stopped, then a SIGHUP signal followed 

364 My a SIGCONT signal shall be sent to each process in the newly orphaned 

365 process group. 

366 These consequences shall occur on process termination for any reason. 

367 3.2. 2.3 Returns 

368 The _exit( ) function cannot return to its caller. 

369 3.2. 2.4 Cross-References 

370 closeO, 6.3.1; sigactionO, 3.3.4; wait, 3.2.1. 
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3.3 Signals 


3.3.1 Signal Concepts 

3.3.1.1 Signal Names 

The <signal . h> header declares the sigsetj type and the sigaction structure. It 
also defines the following symbolic constants, each of which expands to a distinct 
constant expression of the type void(*)(), whose value matches no declarable 
function. 


Symbolic Description 

Constant 

SIG_DFL Request for default signal handling 
SIGJGN Request that signal be ignored 


The type sigsetj. is used to represent sets of signals. It is always an integral or 
structure type. Several functions used to manipulate objects of type sigsetj are 
defined in 3.3.3. 

The <signal .h> header also declares the constants that are used to refer to the 
signals that occur in the system. Each of the signals defined by this part of 
ISO/IEC 9945 and supported by the implementation shall have distinct, positive 
integral values. The- value zero is reserved for use as the null signal (see 3.3.2). 
An implementation may define additional signals that may occur in the system. 

The constants shown in Table 3-1 shall be supported by all implementations. 

The constants shown in Table 3-2 shall be defined by all implementations. How- 
ever, implementations that do not support job control are not required to support 
these signals. If these signals are supported by the implementation, they shall 
behave in accordance with this part of ISO/IEC 9945. Otherwise, the implementa- 
tion shall not generate these signals, and attempts to send these signals or to 
ex am ine or specify their actions shall return an error condition. See 3.3.2 and 
3.3.4. 

3.3. 1.2 Signal Generation and Delivery 

A signal is said to be generated for (or sent to) a process when the event that 
causes the signal first occurs. Examples of such events include detection of 
hardware faults, timer expiration, and terminal activity, as well as the invocation 
of the killO function. In some circumstances, the same event generates signals 
for multiple processes. 

Each process has an action to be taken in response to each signal defined by the 
system (see 3.3. 1.3). A signal is said to be delivered to a process when the 
appropriate action for the process and signal is taken. 

During the time between the generation of a signal and its delivery, the signal is 
said to be pending. Ordinarily, this interval cannot be detected by an application. 
However, a signal can be blocked from delivery to a process. If the action associ- 
ated with a blocked signal is anything other than to ignore the signal, and if that 
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451 signal is generated for the process, the signal shall remain pending until either it 

462 is unblocked or the action associated with it is set to ignore the the i signal. K < 

453 action associated with a blocked signal is to ignore the signal, and if * a t s.grial i8 

454 generated for the process, it is unspecified whether the signal is discarded 
466 immediately upon generation or remains pending. 

456 Each process has a signal mask that defines the set of signals ^rently blocked 

46? from delivery to it. The signal mask for a process is initialized from that of its 

468 parent. ThI sigactioni), sigprocmask (), and sigsuspendO functions control the 

469 manipulation of the signal mask. 

460 The determination of which action is taken in response to a signal is made at the 

461 time the signal is delivered, allowing for any changes since the time of generation. 

462 This determination is independent of the means by which the signid ! was ong>- 

463 nally generated. If a subsequent occurrence of a pending signal is geierated, it is 

464 implementation defined as to whether the signal is delivered more than once. The 
466 order in which multiple, simultaneously pending signals are delivered to a pro- 
466 cess is unspecified. 

46, When any stop signal (SIGSTOP. SIGTSTP, SIGTTIN, SIGTTOU)isgeneratcd for a 

468 process, any pending SIGCONT signals for that process shall be d^carded. Con- 

469 versely, when SIGCONT is generated for a process, all pending stop signals 

4.0 that process shall be discarded. When SIGCONT is generated for a process that is 

4.1 stopped, the process shall be continued, even if the SIGCONT signal is blocked or 

472 ignored. If SIGCONT is blocked and not ignored, it shall remain pending unt 

473 either unblocked or a stop signal is generated for the process. 

474 An implementation shall document any conditions not specified by this part of 

476 ISO/IEC 9945 under which the implementation generates signals. (See l.J.l. .) 

476 3.3.1.3 Signal Actions 

477 There are three types of actions that can be associated with a ^IG DFL, 

478 SIG IGN, or a pointer to a function. Initially, all signals shall be set to - 

479 SIG_IGN prior to entry of the main () routine (see 3.1.2). The actions prescribed by 

480 these values are as follows: 

481 (1) SIG_DFL — signal-specific default action 

482 (a) The default actions for the signals defined in this part of 

483 ISO/IEC 9945 are specified in Table 3-1 and Table 3-2. 

484 (b) If the default action is to stop the process, the execution of that P™‘ 

485 cess is temporarily suspended. When a process stops, a SIGCHLD 
signal shall be generated for its parent process, unless the parent 

487 process has set the SA_NOCLDSTOP flag (see 3.3.4). While a process 

488 is stopped, any additional signals that are sent to the process shall 

489 not be delivered until the process is continued except SIGKJLL, 

i 490 which always terminates the receiving process. A process that is a 

491 member of an orphaned process group shall not be allowed to stop 

492 in response to the SIGTSTP, SIGTTIN, or SIGTTOU sipials. In cases 

493 where delivery of one of these signals would stop such a process, the 

494 signal shall be discarded. 
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(c) Setting a signal action to SIG_DFL for a signal that is pending, and 
whose default action is to ignore the signal (for example, SIGCHLD), 
shall cause the pending signal to be discarded, whether or not it is 
blocked. 

(2) SIG_IGN — ignore signal 

(a) Delivery of the signal shall have no effect on the process. The 
behavior of a process is undefined after it ignores a SIGFPE, SIGILL, 
or SIGSEGV signal that was not generated by the killO function or 
the raise () function defined by the C Standard (2). 

(b) The system shall not allow the action for the signals SIGKILL or 
SIGSTOP to be set to SIG.IGN. 

(c) Setting a signal action to SIG_IGN for a signal that is pending shall 
cause the pending signal to be discarded, whether or not it is 
blocked. 

(d) If a process sets the action for the SIGCHLD signal to SIG_IGN, the 
behavior is unspecified. 

(3) pointer to a function — catch signal 

(a) On delivery of the signal, the receiving process is to execute the 
signal-catching function at the specified address. After returning 
from the signal-catching function, the receiving process shall 
resume execution at the point at which it was interrupted. 

(b) The signal-catching function shall be entered as a C language func- 
tion call as follows: 

void func (int signo) ; | 

where func is the specified signal-catching function and signo is the 
signal number of the signal being delivered. 

(c) The behavior of a process is undefined after it returns normally 
from a signal-catching function for a SIGFPE, SIGILL, or SIGSEGV 
signal that was not generated by the kill{) function or the raise () 
function defined by the C Standard (2). 

(d) The system shall not allow a process to catch the signals SIGKILL 
and SIGSTOP. 

(e) If a process establishes a signal-catching function for the SIGCHLD 
signal while it has a terminated child process for which it has not 
waited, it is unspecified whether a SIGCHLD signal is generated to 
indicate that child process. 

(f) When signal-catching functions are invoked asynchronously with 
process execution, the behavior of some of the functions defined by 
this part of ISO/IEC 9945 is unspecified if they are called from a 
signal-catching function. The following table defines a set of func- 
tions that shall be reentrant with respect to signals (that is, appli- 
cations may invoke them, without restriction, from signal-catching 
functions). 
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538 

_exit() 

fstatO 

readd 

sysconft ) 

539 

access 0 

getegidd 

renamed 

tcdraind 

540 

alarmd 

geteuidd 

rmdirl ) 

tcflowd 

541 

cfgetispeedi ) 

getgidi) 

setgid () 

tcflushX ) 

542 

cfgetospeedd 

getgroupsO 

setpgidd 

tcgetattrl ) 

543 

cfsetispeedd 

getpgrpO 

setsidd 

tcgetpgrpd 

544 

cfsetospeedd 

getpidO 

setuidd 

tcsendbreakd 

545 

chdiri ) 

getppidO 

sigactionO 

tcsetattri ) 

546 

chmodd 

getuidO 

sigaddsetO 

tcsetpgrpd 

647 

chouind 

kill(.) 

sigdelsetd 

timed 

548 

close () 

link () 

sigemptysetd 

timesd 

549 

creatO 

IseekQ 

sigfillsetd 

umaskd 

550 

dup20 

mkdirX ) 

sigismemberi ) 

unamed 

651 

dupd 

mkfifod 

sigpendingi ) 

unlinkd 

652 

execle 0 

open () 

sigprocmask 0 

utimed 

553 

execvel ) 

pathconfX ) 

sigsuspendd 

waitd 

554 

fcntld 

paused 

sleep 0 

uiaitpidd 

556 

fork () 

piped 

statd 

writed 


All POSIICI functions not in the preceding table and all functions 
defined in the C Standard (2) not stated to be callable from a 
signal-catching function are considered to be unsafe with respect to 
signals. In the presence of signals, all functions defined by this part 
of ISO/IEC 9945 or by the C Standard (2) shall behave as defined (by 
the defining standard) when called from or interrupted by a signal- 
catching function, with a single exception: when a signal interrupts 
an unsafe function and the signal-catching function calls an unsafe 
function, the behavior is undefined. 


665 3.3. 1.4 Signal Effects on Other Functions 

666 Signals affect the behavior of certain functions defined by this part of 

667 ISO/IEC 9945 if delivered to a process while it is executing such a function. If the 

668 action of the signal is to terminate the process, the process shall be terminated 

569 and the function shall not return. If the action of the signal is to stop the process, 

570 the process shall stop until continued or terminated. Generation of a SIGCONT 

571 signal for the process causes the process to be continued, and the original function 

572 shall continue at the point where the process was stopped. If the action of the sig- 

673 nal is to invoke a signal-catching function, the signal-catching function shall be 

674 invoked; in this case, the original function is said to be interrupted by the signal. 

575 If the signal-catching function executes a return, the behavior of the interrupted 

576 function shall be as described individually for that function. Signals that are 

677 ignored shall not affect the behavior of any function; signals that are blocked shall 

678 not affect the behavior of any function until they are delivered. 
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579 3.3.2 Send a Signal to a Process 

580 Function: killO 

581 3.3.2.1 Synopsis 

582 finclude <sys/types . h> 

583 #include <signal.h> 

584 int kill(pid_t pid, int sig) ; 

585 3.3.2.2 Description 

586 The killO function shall send a signal to a process or a group of processes 

587 specified by pid. The signal to be sent is specified by sig and is either one from 

588 the list given in 3 . 3 . 1.1 or zero. If sig is zero (the null signal), error checking is 

589 performed, but no signal is actually sent. The null signal can be used to check the 

590 validity of pid . 

591 For a process to have permission to send a signal to a process designated by pid> 

592 the retil or effective user ID of the sending process must match the real or effective 

693 user ID of the receiving process, unless the sending process has appropriate 

594 privileges. If {_POSIX t _SAVED_IDS} is defined, the saved set-user-ID of the receiv- 

696 ing process shall be checked in place of its effective user ID. 

596 If pid is greater than zero, sig shall be sent to the process whose process ID is 

597 equal to pid. 

598 If pid is zero, sig shall be sent to all processes (excluding an unspecified set of sys- 

599 tem processes) whose process group ID is equal to the process group ID of the 

eoo sender and for which the process has permission to send a signal. 

601 If pid is - 1 , the behavior of the killO function is unspecified. 

602 If pid is negative, but not - 1 , sig shall be sent to all processes (excluding an 

603 unspecified set of system processes) whose process group ID is equal to the abso- 

604 lute value of pid and for which the process has permission to send a signal. 

606 If the value of pid causes sig to be generated for the sending process, and if sig is 

606 not blocked, either sig or at least one pending unblocked signal shall be delivered 

607 to the sending process before the killO function returns. 

608 If the implementation supports the SIGCONT signal, the user ID tests described 

609 above shall not be applied when sending SIGCONT to a process that is a member 

6 10 of the same session as the sending process. 

6 11 An implementation that provides extended security controls may impose further 

612 implementation-defined restrictions on the sending of signals, including the null 

613 signal. In particular, the system may deny the existence of some or all of the 

614 processes specified by pid. 

615 The kill() function is successful if the process has permission to send sig to any of 

616 the processes specified by pid. If the killO function fails, no signal shall be sent. 
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617 3.3.2.3 Returns 

6 is Upon successful completion, the function shall return a value of zero. Otherwise, 

619 a value of -1 shall be returned and errno shall be set to indicate the error. 

620 3.3.2.4 Errors 

621 If any of the following conditions occur, the killO function shall return -1 and set 

622 errno to the corresponding value: 

623 [EINVAL] The value of the sig argument is an invalid or unsupported sig- 

624 nal number. 

626 [EPERM] The process does not have permission to send the signal to any 

626 receiving process. 

627 [ESRCH] No process or process group can be found corresponding to that 

628 specified by pid. 

629 3.3.2.5 Cross-References 

630 getpidO, 4.1.1; setsidO, 4.3.2; sigactionO, 3.3.4; <signal.h>, 3.3.1. 


631 3.3.3 Manipulate Signal Sets 

632 Functions: sigemptysetO. sigfillsetO, sigaddsetO. sigdelsetO, sigismemberO 

633 3.3.3.1 Synopsis 

634 #include <signal.h> 

636 int sigemptyset (sigset_t *set) ; 

636 int sigfillset (sigset_t •set); 

637 int sigaddset (sigset_t *setf^i.nt signo) ; 

638 int sigdelset (sigset__t *set, int signo); 

639 int sigismember (const sigset_t *set, int signo). 


640 3.3.3.2 Description 


641 The sigsetops primitives manipulate sets of signals. They operate on data objects 

642 addressable by the application, not on any set of signals known to the system, 

643 such as the set blocked from delivery to a process or the set pending for a process 

644 (see 3 . 3 . 1 ). 

646 The sigemptysetO function initializes the signal set pointed to by the argument 

646 set, such that all signals defined in this part of ISO/IEC 9945 are excluded. 

647 The sigfillsetO function initializes the signal set pointed to by the argument set, 

648 such that all signals defined in this part of ISO/IEC 9945 are included. 


649 Applications shall call either sigemptysetO or sigfillsetO at least once for each 

650 object of type sigsetj prior to any other use of that object. If such an object is not 
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651 initialized in this way, but is nonetheless supplied as an argument to any of the 

652 sigaddsetO , sigdelset ( ), sigismember( ), sigactionO, sigprocmaskO, sigpendingi ), or 

653 sigsuspendO functions, the results are undefined. 

654 The sigaddsetO and sigdelsetO functions respectively add or delete the individual 

656 signal specified by the value of the argument signo to or from the signal set 

656 pointed to by the argument set. 

657 The sigismember( ) function tests whether the signal specified by the value of the 
ess argument signo is a member of the set pointed to by the argument set. 

659 3.S.3.3 Returns 

660 Upon successful completion, the sigismemberO function returns a value of one if 

661 the specified signal is a member of the specified set, or a value of zero if it is not. 

662 Upon successful completion, the other functions return a value of zero. For all of 

663 the above functions, if an error is detected, a value of —1 is returned, and errno is 

664 set to indicate the error. 

666 3.3.3.4 Errors 

666 For each of the following conditions, if the condition is detected, the sigaddsetO , 

667 sigdelsetO, and sigismemberO functions shall return —1 and set errno to the 

668 corresponding value: 

669 [EINVAL] The value of the signo argument is an invalid or unsupported 

670 signal number. 

671 3. 3. 3.5 Cross-References 

672 sigactionO, 3.3.4; < signal .h>, 3.3.1; sigpendingO, 3.3.6; sigprocmask (), 3.3.5; 

673 sigsuspendO, 3.3.7. 


674 3.3.4 Examine and Change Signal Action 

676 Function: sigactionO 

676 3.3.4.1 Synopsis 

677 #include <signal.h> 

678 int sigaction (int sig, const struct sigaction *act , 

679 struct sigaction •oact) ; 

680 3.3.4.2 Description 

681 The sigactionO function allows the calling process to examine or specify (or both) 

682 the action to be associated with a specific signal. The argument sig specifies the 

683 signal; acceptable values are defined in 3.3.1. 1. 

684 The structure sigaction, used to describe an action to be taken, is defined in the 


58 


3 Process Primitives 



ISO/IEC 9946-1: 1990 
IEEE Sid 1003.1-1990 


Part 1: SYSTEM API [C LANGUAGE] 


686 header <signal . h> to include at least the following members 


Member Member 

Type Name 

void 0)0 sa_handler SIG_DFL, SIGJGN, or pointer to a function. 
sigsetj sajnask Additional set of signals to be blocked during 

execution of signal-catching function. 
int sa Jlags Special flags to affect behavior of signal. 


Description 


Implementations may add extensions as permitted in 1.3. 1.1, point (2). Adding | 
extensions to this structure, which might change the behavior of the application 
with respect to this standard when those fields in the structure are uninitialized, 
also requires that the extensions be enabled as required by 1.3.1. 1. I 

If the argument act is not NULL, it points to a structure specifying the action to 
be associated with the specified signal. If the argument oact is not NULL, the 
action previously associated with the signal is stored in the location pointed to by 
the argument oact. If the argument act is NULL, signal handling is unchanged by 
this function call; thus, the call can be used to enquire about the current handling 
of a given signal. The sajiandler field of the sigaction structure identifies the 
action to be associated with the specified signal. If the sa_handler field specifies a 
signal-catching function, the sa_mask field identifies a set of signals that shall be 
added to the signal mask of the process before the signal-catching function is 
invoked. The S1GKILL and SIGSTOP signals shall not be added to the signal mask 
using this mechanism; this restriction shall be enforced by the system without 
causing an error to be indicated. 

The sajlags field can be used to modify the behavior of the specified signal. 

The following flag bit, defined in the header <signal . h>, can be set in sajlags : 


Symbolic Description 

Constant — — 

SA_NOCLDSTOP Do not generate SIGCHLD when children stop. 


If sig is SIGCHLD and the SA.NOCLDSTOP flag is not set in sajlags, and the 
implementation supports the SIGCHLD signal, a SIGCHLD signal shall be gen- 
erated for the calling process whenever any of its child processes stop. If sig is 
SIGCHLD and the SA_NOCLDSTOP flag is set in sajlags, the implementation 
shall not generate a SIGCHLD signal in this way. 

When a signal is caught by a signal-catching function installed by the sigactionO 
function, a new signal mask is calculated and installed for the duration of the 
signal-catching function [or until a call to either the sigprocmask () or sl &' 
suspendO function is made]. This mask is formed by taking the union of the 
current signal mask and the value of the sa_mask for the signal being delivered 
and then including the signal being delivered. If and when the users signal 
handler returns normally, the original signal mask is restored. 

Once an action is installed for a specific signal, it remains installed until another 
action is explicitly requested [by another call to the sigactionO function] or until 
one of the exec functions is called. 
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728 If the previous action for sig had been established by the signalO function, 

729 defined in the C Standard (2), the values of the fields returned in the structure 

730 pointed to by octet are unspecified and, in particular, oact->sv_handler is not 

731 necessarily the same value passed to the signalO function. However, if a pointer 

732 to the same structure or a copy thereof is passed to a subsequent call to the sigac- 

733 tionO function via the act argument, handling of the signal shall be as if the origi- 

734 nal call to the signals ) function were repeated. 

73 s If the sigactionO function fails, no new signal handler is installed. 

736 It is unspecified whether an attempt to set the action for a signal that cannot be I 

737 caught or ignored to SIG_DFL is ignored or causes an error to be returned with I 

738 errno set to 1EINVAL). j 

739 3.3.4.3 Returns 

740 Upon successful completion, a value of zero is returned. Otherwise, a value of -I 

741 is returned and errno is set to indicate the error. 

742 3.3.4L4 Errors 

743 If any of the following conditions occur, the sigactionO function shall return -1 

744 and set errno to the corresponding value: 

746 [EINVAL] The value of the sig argument is an invalid or unsupported sig- 

746 nal number, or an attempt was made to catch a signal that can- 

not be caught or to ignore a signal that cannot be ignored. See I 

748 3.3.1. 1. 

749 For each of the following conditions, when the condition is detected and the imple- I 

760 mentation treats it as an error, the sigactionO function shall return a value of-1 I 

761 and set errno to the corresponding value. 

752 [EINVAL] An attempt was made to set the action to SIG_DFL for a signal | 

763 that cannot be caught or ignored (or both). 

754 3.3.4.5 Cross-References 

755 kilio, 3 3 2; <signal ,h>, 3.3.1; sigprocmaskO, 3.3.5; sigsetops, 3.3.3; sig- 

756 suspendO, 3.3.7. ’ s 

767 3.3.5 Examine and Change Blocked Signals 

768 Function: sigprocmaskO 

769 3.3.5.1 Synopsis 

760 #include <signal.h> 

761 int sigprocmask (int how, const sigset_t *set, sigset_t *oset) ; \ 
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3.3.5.2 Description 

The sigprocmask () function is used to examine or change (or both) the signal 
mask of the calling process. If the value of the argument set is not NULL, it 
points to a set of signals to be used to change the currently blocked set. 

The value of the argument how indicates the manner in which the set is changed 
and shall consist of one of the following values, as defined in the header 
<signal .h>: 


769 

770 

771 

772 

773 

774 
776 

776 

777 

778 

779 

780 

781 

782 If there are any pending unblocked signals after the call to the sigprocmask () 

783 function, at least one of those signals shall be delivered before the sigprocmaskO 

784 function returns. 

786 It is not possible to block the SIGKILL and SIGSTOP signals; this shall be enforced 

786 by the system without causing an error to be indicated. 

787 If any of the SIGFPE, SIGILL, or SIGSEGV signals are generated while they are 

788 blocked, the result is undefined, unless the signal was generated by a call to the 

789 killO function or the raise () function defined by the C Standard {2}. 

790 If the sigprocmask () function fails, the signal mask of the process is not changed 

791 by this function call. 


Name 

SIGJBLOCK 

SIG_UNBLOCK 


SIGJ3ETMASK 


Description 

The resulting set shall be the union of the current set and 
the signal set pointed to by the argument set. 

The resulting set shall be the intersection of the current set 
and the complement of the signal set pointed to by the argu- 
ment set. 

The resulting set shall be the signal set pointed to by the 
argument set. 


If the argument oset is not NULL, the previous mask is stored in the space 
pointed to by oset. If the value of the argument set is NULL, the value of the 
argument how is not significant and the signal mask of the process is unchanged 
by this function call; thus, the call can be used to enquire about currently blocked 
signals. 


792 3.3.5.3 Returns 

793 Upon successful completion a value of zero is returned. Otherwise, a value of -1 

794 is returned and errno is set to indicate the error. 


795 3.3.5.4 Errors 

,796 If any of the following conditions occur, the sigprocmask () function shall return -1 

797 and set errno to the corresponding value: 

798 [EINVAL] The value of the how argument is not equal to one of the 

799 defined values. 
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809 The sigpendingi) function shall store the set of signals that are blocked from 

810 delivery and pending for the calling process in the space pointed to by the argu- 

811 mentse*. J 6 

812 3.3.6.3 Returns 

813 Upon successful completion, a value of zero is returned. Otherwise, a value of-1 
si4 is returned and errno is set to indicate the error. 


sis 3.3.G.4 Errors 

816 J h ‘ s p f rt of ISO/1EC 9945 does not specify any error conditions that are required 

817 to be detected for the sigpendingi ) function. Some errors may be detected under I 

818 conditions that are unspecified by this part of ISO/IEC 9945. 

si9 3.3.6.5 Cross-References 

820 <signal ,h>, 3.3.1; sigprocmask (), 3.3.5; sigsetops, 3.3.3. 

82 1 3.3.7 Wait for a Signal 

822 Function: sigsuspend() 

823 3.3. 7.1 Synopsis 

824 #include <signal.h> 

826 int sigsuspend (const 3igset_t * sigmas k ) ; | 
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826 3.3.7.2 Description 

827 The sigsuspendO function replaces the signal mask of the process with the set of 

828 signals pointed to by the argument sigmask and then suspends the process until 

829 delivery of a signal whose action is either to execute a signal-catching function or 

830 to terminate the process. 

831 If the action is to terminate the process, the sigsuspendO function shall not 

832 return. If the action is to execute a signal-catching function, the sigsuspendO 

833 shall return after the signal-catching function returns, with the signal mask 

834 restored to the set that existed prior to the sigsuspendO call. 

835 It is not possible to block those signals that cannot be ignored, as documented in 

836 3.3.1; this shall be enforced by the system without causing an error to be 

837 indicated. 


838 3.S.7.3 Returns 

839 Since the sigsuspendO function suspends process execution indefinitely, there is 

840 no successful completion return value. A value of -1 is returned and errno is set 

841 to indicate the error. 


842 3.3.7.4 Errors 

843 If any of the following conditions occur, the sigsuspendO function shall return —1 

844 and set errno to the corresponding value: 

845 [EINTR] A signal is caught by the calling process, and control is 

846 returned from the signal-catching function. 


847 3.3.7.5 Cross-References 

848 pause 0, 3.4.2; sigactionO, 3.3.4; <signal ,h>, 3.3.1; sigpendingO, 3.3.6; sigproc- 

849 maskO, 3.3.5; sigsetops, 3.3.3. 


850 3.4 Timer Operations 

861 A process can suspend itself for a specific period of time with the sleep 0 function 

852 or suspend itself indefinitely with the pauseO function until a signal arrives. The 

853 alarmO function schedules a signal to arrive at a specific time, so a pause 0 

854 suspension need not be indefinite. 


ass 3.4.1 Schedule Alarm 

866 Function: alarmO 
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857 3.4. 1.1 Synopsis 

858 unsigned int alarm (unsigned int seconds ); | 

869 3.4.1.2 Description 

860 The alarm () function shall cause the system to send the calling process a 

861 SIGALRM signal after the number of real-time seconds specified by seconds have 

862 elapsed. 

863 Processor scheduling delays may cause the process actually not to begin handling 

864 the signal until after the desired time. 

865 Alarm requests are not stacked; only one SIGALRM generation can be scheduled 

866 in this manner. If the SIGALRM has not yet been generated, the call will result in 

867 rescheduling the time at which the SIGALRM will be generated. 

868 If seconds is zero, any previously made alarmO request is canceled. 

869 3.4. 1.3 Returns 

870 If there is a previous alarm () request with time remaining, the alarmO function | 

871 shall return a nonzero value that is the number of seconds until the previous | 

872 request would have generated a SIGALRM signal. Otherwise, the alarmO func- | 

873 tion shall return zero. | 

874 3.4. 1.4 Errors 

875 The alarmO function is always successful, and no return value is reserved to indi- 

876 cate an error. 

877 3.4. 1.5 Cross-References 

878 exec , 3.1.2; forkO, 3.1.1; pauseO, 3.4.2; sigactionO, 3.3.4; oignal .h>, 3 .3.1. 

879 3.4.2 Suspend Process Execution 

880 Function: pause () 

881 3.4.2.1 Synopsis 

882 int pause (void); j 

883 3.4.2.2 Description 

884 The pause 0 function suspends the calling process until delivery of a signal whose 

885 action is cither to execute a signal-catching function or to terminate the process. 

886 If the action is to terminate the process, the pauseO function shad not return. 

887 If the action is to execute a signal-catching function, the pauseO function oLqH 

888 return after the signal-catching function returns. 
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889 3.4.2.3 Returns 

890 Since the pauseO function suspends process execution indefinitely, there is no 

891 successful completion return value. A value of -1 is returned and errno is set to 

892 indicate the error. 

i 

893 3.4.2.4 Errors 

894 If any of the following conditions occur, the pauseO function shall return -1 and 
896 set errno to the corresponding value: 

896 [EINTR] A signal is caught by the calling process, and control is 

89 7 returned from the signal-catching function. 

898 3.4.2.5 Cross-References 

899 alarmO, 3.4.1; killO, 3.3.2; wait, -3. 2.1; 3.3. 1.4. 

900 3.4 J Delay Process Execution 

901 Function: sleepO 

902 3.4.3.1 Synopsis 

903 unsigned int sleep (unsigned int seconds); ' 

904 3.4.3.2 Description 

906 The sleep 0 function shall cause the current process to be suspended from execu- 

906 tion until either the number of real-time seconds specified by the argument 

907 seconds have elapsed or a signal is delivered to the calling process and its action 

908 is to invoke a signal-catching function or to terminate the process. The suspen- 

909 sion time may be longer than requested due to the scheduling of other activity by 

910 the system. 

9 11 If a SIGALRM signal is generated for the calling process during execution of the 

912 sleep 0 function and the SIGALRM signal is being ignored or blocked from delivery, 

913 it is unspecified whether sleep 0 returns when the SIGALRM signal is scheduled. 

914 If the signal is being blocked, it is also unspecified whether it remains pending 

915 after the sleep ( ) function returns or is discarded. 

916 If a SIGALRM signal is generated for the calling process during execution of the 

917 sleepO function, except as a result of a prior call to the alarmO function, and if 

918 the SIGALRM signal is not being ignored or blocked from delivery, it is unspecified 

919 whether that signal has any effect other than causing the sleep 0 function to 

920 return. 

921 If a signal-catching function interrupts the sleepO function and either examines 

922 or changes the time a SIGALRM is scheduled to be generated, the action associ- 

923 ated with the SIGALRM signal, or whether the SIGALRM signal is blocked from 

924 delivery, the results are unspecified. 
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925 If a signal-catching function interrupts the sleepO function and calls the 

926 siglongjmp () or longjmpO function to restore an environment saved prior to the 

92? sleep () call, the action associated with the SIGALRM signal and the time at which 

928 a SIGALRM signal is scheduled to be generated are unspecified. It is also 

929 unspecified whether the SIGALRM signal is blocked, unless the process’s signal 

930 mask is restored as part of the environment (see 8.3.1). 

93 1 3.4.3.S Returns 

932 If the sleepO function returns because the requested time has elapsed, the value 

933 returned shall be zero. If the sleepO function returns due to delivery of a signal, 

934 the value returned shall be the unslept amount (the requested time minus the 

935 time actually slept) in seconds. 

936 3.4.3.4 Errors 

937 The sleepO function is always successful, and no return value is reserved to indi- 

938 cate an error. 


939 3.4.3.5 Cross-References 

940 alarmO, 3.4.1; pauseO, 3.4.2; sigactionO, 3 . 3 . 4 . 


Section 4: Process Environment 

1 4.1 Process Identification 

2 4.1.1 Get Process and Parent Process IDs 

3 Functions: getp idO, getppid ( ) 


8 4.1. 1.2 Description 

9 The getpidO function returns the process ID of the calling process. 

to The getppidO function returns the parent process ID of the calling process. 

it 4.1. 1.3 Returns 

12 See 4.1. 1.2. 

13 4.1.1.4 Errors 

14 The getpidO and getppidO functions are always successful, and no return value is 

16 reserved to indicate an error. 

16 4.1.1.5 Cross-References 

17 exec, 3.1.2; forkO, 3.1.1; killO, 3.3.2. 


4 4.1. 1.1 Synopsis 

6 ((include Oys/types . h> 

6 pid_t getpid (void) ; ' 

7 pid t getppid (void) ; 




) 

i 

: : 

P 
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is 4.2 User Identification 

19 4.2.1 Get Real User, Effective User, Real Group, and Effective Group IDs 

20 Functions: getuid( ), geteuidO, getgidO, getegidC) 

21 4.2.1.1 Synopsis 

22 #include <sya/types . h> 

23 uid_t getuid ( void) ; 

24 uid_t geteuid (void) ; 

25 gid_t getgid ( void) ; 

26 gid_t getegid (void) ; 

27 4.2.1.2 Description 

28 The getuidO function returns the real user ID of the calling process. 

29 The geteuidO function returns the effective user ID of the calling process. 

30 The getgidO function returns the real group ID of the calling process. 

31 ThegetegidO function returns the effective group ID of the calling process. 

32 4.2. 1.3 Returns 

33 See 4.2.1. 2. 

34 4.2.1.4 Errors 

35 The getuidO, geteuidO, getgidO, and getegidO functions are always successful, 

36 and no return value is reserved to indicate an error. 

37 4. 2. 1.5 Cross-References 

38 setuidO, 4.2.2. 

39 4.2.2 Set User and Group IDs 

40 Functions: setuidO, setgidO 

41 4.2.2. 1 Synopsis 

42 finclude <sys/types . h> 

43 int setuid (uid_t uid) ; 

44 int setgid (gid_t gid) ; 
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4.2.2.2 Description 

If LPOSIX_SAVED_IDS) is defined: 

(1) If the process has appropriate privileges, the setuidO function sets the 
real user ID, effective user ID, and the saved set-user-ID to uid . 

(2) If the process does not have appropriate privileges, but uid is equal to the 
real user ID or the saved set-user-ID, the setuidO function sets the effec- 
tive user ID to uid\ the real user ID and saved set-user-ID remain 
unchanged by this function call. 

(3) If the process has appropriate privileges, the setgidO function sets the 
real group ID, effective group ID, and the saved set-group-ID to gid. 

(4) If the process does not have appropriate privileges, but gid is equal to the 
real group ID or the saved set-group-ID, the setgidO function sets the 
effective group ID to gid ; the real group ID and saved set-group-ID remain 
unchanged by this function call. 

Otherwise: 

(1) If the process has appropriate privileges, the setuidO function sets the 
real user ID and effective user ID to uid. 

(2) If the process does not have appropriate privileges, but uid is equal to the 
real user ID, the setuidO function sets the effective user ID to uid ; the 
real user ID remains unchanged by this function call. 

(3) If the process has appropriate privileges, the setgidO function sets the 
real group ID and effective group ID to gid. 

(4) If the process does not have appropriate privileges, but gid is equal to the 
real group ID, the setgidO function sets the effective group ID to gid ; the 
real group ID remains unchanged by this function call. 

Any supplementary group IDs of the calling process remain unchanged by these 

function calls. 

4.2.2.3 Returns 

Upon successful completion, a value of zero is returned. Otherwise, a value of-1 

is returned and errno is set to indicate the error. 

4.2.2.4 Errors 

If any of the following conditions occur, the setuidO function shall return -1 and 

set errno to the corresponding value: 

[EINVAL] The value of the uid argument is invalid and not supported by 
the implementation. 

[EPERM] The process does not have appropriate privileges and uid does 
not match the real user ID or, if {JP0SIXJ3AVED_IDS} is 
defined, the saved set-user-ID. 
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If any of the following conditions occur, the setgidO function shall return -1 and 
set errno to the corresponding value: 

[EINVAL] The value of the gid argument is invalid and not supported by 
the implementation. 

[EPERM] The process does not have appropriate privileges and gid does 
not match the real group ID or, if (JPOSIX_SAVED_IDS) is 
defined, the saved set-group-ID. 


so 4.2. 2.5 Cross-References 

91 exec, 3.1.2, gctuidO, 4.2.1. 

92 4.2.3 Get Supplementary Group IDs 

99 Function: getgroups( ) 

94 4.2.3. 1 Synopsis 

96 #include <sys/type3 . h> 

96 int getgroups (int gidsetsize, gid_t grouplist [ ] ) ; 

97 4.2.3.2 Description 

98 The getgroups () function fills in the array grouplist with the supplementary group 

99 IDs of the calling process. The gidsetsize argument specifies the number of ele- 

100 ments in the supplied array grouplist. The actual number of supplementary 

101 group IDs stored in the array is returned. The values of array entries with indices 

102 larger than or equal to the returned value are undefined. 

103 As a special case, if the gidsetsize argument is zero, getgroupsO returns the 

104 number of supplemental group IDs associated with the calling process without 

105 modifying the array pointed to by the grouplist argument. 

106 4.2.3.3 Returns 

107 Upon successful completion, the number of supplementary group IDs is returned. 

108 This value is zero if (NGROUPS_MAX} is zero. A return value of -1 indicates 

109 failure, and errno is set to indicate the error. 


no 4.2.3.4 Errors 

111 If any of the following conditions occur, the getgroupsO function shall return -1 

112 and set errno to the corresponding value: 

H3 [EINVAL] The gidsetsize argument is not equal to zero and is less than 


the number of supplementary group IDs. 
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116 setgidO, 4.2.2. 


117 4.2.4 Get User Name 


118 Functions: getloginO 


119 4.2.4.1 Synopsis 


120 char *getlogin (void) 


121 4.2.4.2 Description 

122 The getloginO function returns a pointer to a string giving a user name associated j 

123 with the calling process, which is the login name associated with the calling 

124 process. 

125 If getloginO returns a non-NULL pointer, that pointer points to the name under 

126 which the user logged in, even if there are several login names with the same 

127 user ID. 


129 4 .2.4.3 Returns 


The getloginO function returns a pointer to a string containing the user’s login 
name, or a NULL pointer if the user’s login name cannot be found. 

The return value from getloginO may point to static data and, therefore, may be 
overwritten by each call. 


135 4.2.4.4 Errors 


This part of ISO/IEC 9945 does not specify any error conditions that are required 
to be detected for the getloginO function. Some errors may be detected under con- 
ditions that are unspecified by this part of ISO/IEC 9945. 


139 4.2.4.5 Cross-References 


140 getpwnamO, 9.2.2; getpwuidO, 9.2.2. 


4.2 User Identification 


ISO/IEC 9945-1: 1990 
IEEE Std 1003.1-1990 


INFORMATION TECHNOLOGY— POSDC 


141 4.3 Process Groups 

142 4.3.1 Get Process Group ID 

143 Function: getpgrp ( ) 

144 4.3. 1.1 Synopsis 

146 #include <sys/ types . h> 

146 pid_t getpgrp (void) ; | 

147 4.3. 1.2 Description 

148 The getpgrp ( ) function returns the process group ID of the calling process. 

149 4.3.1.3 Returns 

iso See 4. 3. 1.2. 

161 4.3. 1.4 Errors 

* md'cftff™ nCtl0n 18 alWayS SUCCeSSfu1 ’ and n ° r6tUrn Value is to 

154 4.3. 1.5 Cross-References 

155 setpgid (), 4.3.3; setsid(), 4.3.2; sigaction(), 3.3.4. 

166 4.3.2 Create Session and Set Process Group ED 

157 Function: setsid() 

168 4.3.2.1 Synopsis 

159 #include <sys/types . h> 

160 pid_t setsid (void) ; j 

161 4.3.2.2 Description 

1*61 Callmg pr0cess j® not a process group leader, the setsidO function shall 

164 session 3 shnTl The calhng P roces3 sha11 be the session leader of this new 

session shall be the process group leader of a new process group, and shall have 

ibk H “"trolling terminal. The process group ID of the calling process shall be set 
lev Xesfin theT 38 10 ° f ^ CaIhng J pi ; 0Ce3S ' The callin g Process shall be the only 

process in the new process group and the only process in the new session 
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168 4.3.2.3 Returns 

169 Upon successful completion, the setsidi ) function returns the value of the process 

no group ID of the calling process. Otherwise, a value of -1 is returned and errno is | 

m set to indicate the error. I 

172 4.3.2.4 Errors 

173 If any of the following conditions occur, the setsidi) function shall return -1 and 

174 set errno to the corresponding value: 

176 [EPERM] The calling process is already a process group leader, or the 

176 process group ID of\a process other than the calling process 

177 matches the process ID of the calling process. 

ns 4.3.2.5 Cross-References 

179 exec, 3.1.2; _exitO, 3.2.2; fork 0 , 3-i.l \getpidO, 4.1.1; killO, 3.3.2; setpgidO, 4.3.3; 
iso sigactionO, 3.3.4. 


lai 4.3.3 Set Process Group ID for Job Control 

182 Function: setpgidi ) 

183 4.3.3.1 Synopsis 

184 # include <sys / types . h> 

186 int setpgid (pid_t pid, pid_t pgid) ; 

186 4.3.3.2 Description 

187 If (_POSDCJOB_CONTROL) is defined: 

188 The setpgidO function is used to either join an existing process group or 

189 create a new process group within the session of the calling process. The 

190 process group ID of a session leader shall not change. Upon successful com- 

191 pletion, the process group ID of the process with a process ID that matches 

192 pid shall be set to pgid. As a special case, if pid is zero, the process ID of 

193 the calling process shall be used. Also, if pgid is zero, the process ID of the 

194 indicated process shall be used. 

195 Otherwise: 

196 Either the implementation shall support the setpgidi ) function as described 

197 above or the setpgidO function shall fail. 

198 4.3.3.3 Returns 

199 Upon successful completion, the setpgidO function returns a value of zero. Other- 

200 wise, a value of -1 is returned and errno is set to indicate the error. 
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201 4.3.3.4 Errors 


202 

203 
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218 
219 


If any of the following conditions occur, the setpgidO function shall return -1 and 
set errno to the corresponding value: 

[EACCES] The value of the pid argument matches the process ID of a child 
process of the calling process, and the child process has success- 
fully executed one of the exec functions. 

[EINVAL] The value of the pgid argument is less than zero or is not a 
value supported by the implementation. 

[ENOSYS] The setpgidO function is not supported by this implementation. 

[EPERM] The process indicated by the pid argument is a session leader. 

The value of the pid argument is valid, but matches the process 
ID of a child process of the calling process, and the child process 
is not in the same session as the calling process. 

The value of the pgid argument does not match the process ID 
of the process indicated by the pid argument, and there is no 
process with a process group ID that matches the value of the 
pgid argument in the same session as the calling process. 

[ESRCH] The value of the pid argument does not match the process ID of 
the calling process or of a child process of the calling process. 


220 4.3.3.5 Cross-References 


221 getpgrp (), 4 . 3 . 1 ; setsidO, 4 . 3 . 2 ; tcsetpgrp (), 7 . 2 . 4 ; exec, 3 . 1 . 2 . 


222 4.4 System Identification 

223 4.4.1 Get System Name 

224 Function: uname () 

226 4.4. 1.1 Synopsis 

226 #include <sys/utsname . h> 

227 int uname (struct utsname +name) ; 

228 4.4. 1.2 Description 

229 The uname 0 function stores information identifying the current operating system 

230 in the structure pointed to by the argument name. 

23 1 The structure utsname is defined in the header <sys/utsname . h> and contains 

232 at least the members shown in Table 4-1. 
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262 4.5.1.2 Description 

263 The time() function returns the value of time in seconds since the Epoch. 

264 The argument tloc points to an area where the return value is also stored. If tloc 
266 is a NULL pointer, no value is stored. 

266 4. 5. 1.3 Returns 

267 Upon successful completion, timeO returns the value of time. Otherwise, a value 

266 of (( timej ) -1) is returned and errno is set to indicate the error. 

269 4.5. 1.4 Errors 

270 This part of ISO/IEC 9945 does not specify any error conditions that are required 

271 to be detected for the timeO function. Some errors may be detected under condi- 

272 tions that are unspecified by this part of ISO/IEC 9945. 

273 4.5.2 Get Process Times 

274 Function: timesO 


276 4.5.2.1 Synopsis 

276 #include <sys/time 3 . h> 

277 clock_t times (struct tms * buffer ) ; 

278 4.5.2.2 Description 

279 The timesO function shall fill the structure pointed to by buffer with time- 

280 accounting information. The type clock J and the tms structure are defined in 

281 <sys /times . h>; the tms structure shall contain at least the following members: 


Member 

Type 

clockjt 

clock_t 

clockj 

clockj 


Member 

Name 

tmsjLitime 
tms _s time 
tms_cutime 
tms_cstime 


Description 

User CPU time. 

System CPU time. 

User CPU time of terminated child processes. 
System CPU time of terminated child processes. 


288 All times are measured in terms of the number of clock ticks used. 

289 The times of a terminated child process are included in the tmsjcutime and 

290 tms_cstime elements of the parent when a waitO or waitpidl ) function returns the 

291 process ID of this terminated child. See 3.2.1. If a child process has not waited 

292 for its terminated children, their times shall not be included in its times. 

293 The value tmsutime is the CPU time charged for the execution of user 

294 instructions. 
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The value tmsjtime is the CPU time charged for execution by the system on 
behalf of the process. 

The value tmsjcutime is the sum of the tmsjutime s and tms_cutime s of the child 
processes. 

The value tms_cstime is the sum of the tmsjtimes and tms _cs times of the child 
processes. 


301 4.S.2.3 Returns 


Upon successful completion, timesO shall return the elapsed real time, in clock 1 
ticks, since an arbitrary point in the past (for example, system start-up time). 
This point does not change from one invocation of timesO within the process to 
another. The return value may overflow the possible range of type clockj. If the 
times 0 function fails, a value of ((clockj) -I) is returned and errno is set to indi- 
cate the error. 


308 4.5.2.4 Errors 

309 This part of ISO/IEC 9945 does not specify any error conditions that are required 

310 to be detected for the timesi ) function. Some errors may be detected under condi- 

311 tions that are unspecified by this part of ISO/IEC 9945. 


312 4.5.2.5 Cross-References 


313 exec, 3.1.2; forkO, 3.1.1; sysconfO, 4.8.1; timeO, 4.5.1; wait 0, 3.2.1. 


314 4.6 Environment Variables 


316 4.6.1 Environment Access 


316 Function: getenv () 


317 4.6.1.1 Synopsis 


318 #include <stdlib.h> 


319 char *getenv (const char *name) 


320 4.6.1.2 Description 

321 The getenvO function searches the environment list (see 2.6) for a string of the 

322 form name -value and returns a pointer to value if such a string is present. If the 

323 specified name cannot be found, a NULL pointer is returned. 
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324 4.6.1.3 Returns 

325 Upon successful completion, the getenv () function returns a pointer to a string 

326 containing the value for the specified name, or a NULL pointer if the specified 

327 name cannot be found. The return value from getenv () may point to static data 

328 and, therefore, may be overwritten by each call. Unsuccessful completion shal l 

329 result in the return of a NULL pointer. 

330 4.6. 1.4 Errors 

331 This part of ISO/I EC 9945 does not specify any error conditions that are required 

332 to be detected for the getenv () function. Some errors may be detected under condi- I 

333 tions that are unspecified by this part of ISO/IEC 9945. 

334 4.6.1.5 Cross-References 

336 3 . 1 . 2 ; 2 . 6 . 


336 4.7 Terminal Identification 


337 4.7.1 Generate Terminal Pathname 

338 Function: ctermidO 

339 4.7.1. 1 Synopsis 

340 #include <stdio.h> 

341 char ♦ctermid (char *s) ; | 

342 4.7.1.2 Description 

343 T'fJ ctermidO function generates a string that, when used as a pathname, refers 

344 to the current controlling terminal for the current process. 

345 If the ctermidO function returns a pathname, access to the file is not guaranteed. 

346 4.7.1.3 Returns 

347 If S is a NULL pointer, the string is generated in an area that may be static (and 

348 “ e l refore ’ ma y be overwritten by each call), the address of which is returned 

349 Otherwise, s is assumed to point to an array of cAar of at least L_ctermid bytes: I 

350 the string is placed in this array and the value of s is returned. The symbolic con- 

351 stant L_ctermid is defined in <stdio.h> and shall have a value greater than 

352 zero. 

353 The CtermidO function shall return an empty string if the pathname that would 
refer to the controlhng terminal cannot be determined or if the function is 

366 unsuccessful. 


78 


4 Process Environment 


Part 1: SYSTEM API [C LANGUAGE] 


ISO/IEC 9945-1: 1990 
IEEE Std 1003.1-1990 


366 4. 7.1.4 Errors 

367 This part of ISOflEC 9945 does not specify any error conditions that are required 

358 to be detected for the ctermidO function. Some errors may be detected under con- 

369 ditions that are unspecified by this part of ISO/IEC 9945. I 

360 4.7. 1.5 Cross-References 

i 

361 ttynameO, 4.7.2. 

362 4.7 .2 Determine Terminal Device Name 

363 Functions : tty name ( ), isatty ( ) 

364 4.7.2. 1 Synopsis 

366 char *ttyname(int fildes) ; 

366 int isatty (int fildes); ^ 

367 4.7.2.2 Description 

368 The ttynameO function returns a pointer to a string containing a null-terminated 

369 pathname of the terminal associated with file descriptor fildes . 

370 The return value of ttynameO may point to static data that is overwritten by each 

371 call. 

372 The isatty 0 function returns 1 if fildes is a valid file descriptor associated with a 

373 terminal, zero otherwise. 

374 4.7.2.3 Returns 

376 The tty name () function returns aJNULL pointer if fildes is not a valid file descrip- 

376 tor associated with a terminal or if the pathname cannot be determined. 

377 4.7.2.4 Errors 

378 This part of ISOflEC 9945 does not specify any error conditions that are required 

379 to be detected for the ttynameO or isattyO functions. Some errors may be 

380 detected under conditions that are unspecified by this part of ISOflEC 9945. I 
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3«i 4.8 Configurable System Variables 


382 4.8.1 Get Configurable System Variables 

383 Function: syscon/X) 


384 4.8.1. 1 Synopsis 

385 #include <uniatd.h> 

386 long sysconf(int name); 


38 7 4.8.1.2 Description 


388 

389 

390 

391 

392 

393 

394 


The sysconfO function provides a method for the application to determine the 
current value of a configurable system limit or option (variable). 

The name argument represents the system variable to be queried. The implemen- 
tatmn shall support all of the variables listed in Table 4-2 and may support oth- 
6rS 'i3 e vanables in Table 4-2 come from climits . h> or <unistd.h> and the 
symbolic constants, defined in <unistd.h>, that are the corresponding values 
used for name. nuc 


418 4.8.1.4 Errors 


419 If any of the following conditions occur, the sysconfX ) function shall return -1 and 

420 set errno to the corresponding value: 

421 [EINVAL] The value of the name argument is invalid. 


422 4.8.1.5 Special Symbol (CLK_TCK) I 

423 The special symbol {CLK_TCK} shall yield the same result as | 

424 sysconf (_sc_clk_tck) . It shall be defined in <time.h>. The symbol | 

425 {CLKJTCK) may be evaluated by the implementation at run time or may be a con- 1 

426 stant. This special symbol is obsolescent. I 


395 

396 ______ 

Table 4-2 - Configurable System Variables 

397 

Variable 

name Value 

398 

399 

400 

401 

402 

403 

404 

406 

406 

407 

408 

[ARGJUAXJ 

{CHILD_MAX} 

clock ticks/second 

{NGROUPS_MAXJ 

(OPEN_MAXJ 

|STREAM_MAX) 

(TZNAMEJdAX) 

LPOSDt_JOB_CONTROL) 

LPOSIX_SAVED_ms) 

LPOSIX_VERSION) 

LSC_ARG_MAX) 

Lscchild_max) 

LSC_CLK_TCK) I 

LSCjyGROUPS_MAX] 

Lsc_open_max) 

LSC_STREAM_MAX) | 

Lsc_tzname_maxi 

Lsc_job_control) 

Lsc_saved_ids) 

LSC_VERSION) 


409 4.8. 1.3 Returns 


410 

411 

412 

413 

414 

415 

416 

417 


If name is an invalid value, sysconfl) shall return -1. If the variable correspond- 
ing to name is associated with functionality that is not supported by the system, 
sysconfl) shall return -1 without changing the value of errno. 

Otherwise, the sysconfO function returns the current variable value on the sys- 
. The value returned shall not be more restrictive than the corresponding 
ImZ ( 8 T 10 016 appllcatlon when was compiled with the 

1 h f f r S rl n S • h> ° r <unistd • h >- Th e value shall not change dur- 
ing the lifetime of the calling process. 


i 

i 

J 

; 

! 

! 

i 

I 

I 


80 


4 Process Environment 


4.8 Configurable System Variables 


81 


ISO/IEC 9945-1: 1990 
IEEE Sid 1003.1- 1990 


Section 5: Files and Directories 


1 The functions in this section perform the operating system services dealing with 

2 the creation and removal of files and directories and the detection and 

3 modification of their characteristics. They also provide the primary methods a 

4 process will use to gain access to files mid directories for subsequent I/O opera- 

5 tions (see Section 6). 

6 5.1 Directories 

7 6.1.1 Format of Directory Entries 

s The header <dirent . h> defines a structure and a defined type used by the direc- 

9 tory routines. 

10 The internal format of directories is unspecified. 

11 The readdiri) function returns a pointer to an object of type struct dirent that 


includes the member: 



Member 

Type 

Member 

Name 

Description 

char [ ] 

djiame 

Null-terminated filename 


16 The array of char djiame is of unspecified size, but the number of bytes preceding | 
U 7 the terminating null character shall not exceed {NAME_MAX}. 

is 5.1.2 Directory Operations 

19 Functions: opendiri), readdiri ), rewinddiri ) , closediri) 

20 5. 1.2.1 Synopsis 

21 tinclude <sys/types . h> 

22 #include <dirent.h> 

23 DIR *opendir (const char *dirname ) ; 

24 struct dirent *readdir(DIR *dirp) ; 

26 void rewinddir (DIR *dirp) ; 

26 int closedir(DIR *dirp) ; 
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27 5. 1.2.2 Description 

28 The type DIR , which is defined in the header <dirent . h>, represents a directory 

29 stream, which is an ordered sequence of all the directory entries in a particular 

30 directory. Directory entries represent files; files may be removed from a directory 

:u or added to a directory asynchronously to the operations described in this sub- I 

32 clause (5.1.2). The type DIR may be implemented using a file descriptor. In that 

33 case, applications will only be able to open up to a total of (OPEN_MAX) files and 

33 directories; see 5.3.1. A successful call to any of the exec functions shall close any I 

35 directory streams that are open in the calling process. j 

3s The opendiri) function opens a directory stream corresponding to the directory 

37 named by the dirname argument. The directory stream is positioned at the first 

38 entry. 

39 The readdirO function returns a pointer to a structure representing the directory 

40 entry at the current position in the directory stream to which dirp refers, and 

41 positions the directory stream at the next entry. It returns a NULL pointer upon 

42 reaching the end of the directory stream. 

43 The readdirO function shall not return directory entries containing empty names. 

44 It is unspecified whether entries are returned for dot or dot-dot. [ 

45 The pointer returned by readdirO points to data that may be overwritten by 

46 another call to readdirO on the same directory stream. This data shall not be 

47 overwritten by another call to readdirO on a different directory stream. 

48 The readdirO function may buffer several directory entries per actual read opera- 

tion, the readdirO function shall mark for update the st_atime field of the direc- 

so tory each time the directory is actually read. 

51 The rewmddirO function resets the position of the directory stream to which dirp 
2 refers to the beginning of the directory. It also causes the directory stream to 
' r , . l u th ® current 3tate of the corresponding directory, as a call to opendirO 
■54 would have done. It does not return a value. 

5f. If a file is removed from or added to the directory after the most recent call to 
opendirO or rewmddir( ), whether a subsequent call to readdiri ) returns an entry 

57 for that file is unspecified. 

58 The closediri ) function closes the directory stream referred to by dirp and returns 
a value of zero if successful. Otherwise, it returns -1 indicating an error. Upon 

“ ™ tur "' "l e va ! ue oldlr P ma y n <> longer point to an accessible object of type DIR 

62 closed 6 deSCnpt ° r 13 USed t0 im P lem ent type DIR, that file descriptor shall be 

63 If the dirp argument passed to any of these functions does not refer to a currently 

64 open directory stream, the effect is undefined. 

“ asing a directory stream after one of the exec family of functions is 

rl ~ d ' After a caU to the f° r >t O function, either the parent or the child (but 

68 r ,) t7 C rr wu ? u r0CeS3ing the director y stream using readdirO or remind- 
er h h If ., b0 l h u the parent and child processes use these functions, the 

69 result is undefined. Either or both processes may use closedirO. 
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70 5.1.2.3 Returns 

71 1 Upon successful completion, opendirO returns a pointer to an object of type DIR. 

72 Otherwise, a value of NULL is returned and errno is set to indicate the error. 

73 Upon successful completion, readdirO returns a pointer to an object of type struct 

74 dirent . When an error is encountered, a value of NULL is returned and errno is 

75 set to indicate the error. When the end of the directory is encountered, a value of 

76 NULL is returned and errno is unchanged by this function call. 

77 1 Upon successful completion, closediri ) returns a value of zero. Otherwise, a value 

78 of-1 is returned and errno is set to indicate the error. 


5.1.2.4 Errors 

If any of the following conditions occur, the opendiri ) function shall return a value 
of NULL and set errno to the corresponding value: 

[EACCES] Search permission is denied for a component of the path prefix | 
of dirname, or read permission is denied for the directory itself. | 

[ENAMETOOLONG] 

The length of the dirname argument exceeds (PATH_MAX), or a 
pathname component is longer than (NAME_MAX) while 
LPOSDC_NO_TRUNC) is in effect. 

[ENOENT] The named directory does not exist, or dirname points to an | 
empty string. I 

[ENOTDUt] A component of dirname is not a directory. 

For each of the following conditions, when the condition is detected, the opendiri ) 
function shall return a value of NULL and set errno to the corresponding value: 

[EMFILE] Too many file descriptors are currently open for the process. 

[ENFILE] Too many file descriptors are currently open in the system. 

For each of the following conditions, when the condition is detected, the readdirO 
function shall return a value of NULL and set errno to the corresponding value: 

[EBADF] The dirp argument does not refer to an open directory stream. 

For each of the following conditions, when the condition is detected, the closediri ) 
function shall return -1 and set errno to the corresponding value: 

[EBADF] The dirp argument does not refer to an open directory stream. 


ioi 5.1.2.5 Cross-References 


102 <dirent .h>, 5.1.1. 
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103 5.2 Working Directory 

104 5-2.1 Change Current Working Directory 

105 Function: chdirQ 

106 5.2. 1.1 Synopsis 

107 int chdir(con3t char *path ) ; 

loa 5.2.1.2 Description 

109 The path argument points to the pathname of a directory. The chdirQ function 
1 o causes the named directory to become the current working directory, that is, the 
ill starting point for path searches of pathnames not beginning with slash. 

m If the cAdir() function fails, the current working directory shall remain 

113 unchanged by this function call. 

114 5.2.1.3 Returns 

lie Upon successful completion, a value of zero is returned. Otherwise, a value of -1 
lie is returned and errno is set to indicate the error. 

117 5.2. 1.4 Errors 

lis If any of the following conditions occur, the chdirQ function shall return -1 and 
H9 set errno to the corresponding value: 

120 [EACCES] Search permission is denied for any component of the path- 

1/1 name. 

122 1 ENAMETOOLONG] 

!“ The P ath argument exceeds (PATHJHAX) in length, or a path- 

aame component is longer than {NAMEJMAX) while 

125 LPOSIX_NO_TRUNC) is in effect. 

126 [ENOTDIR] A component of the pathname is not a directory. 

127 [ENOENT1 The named directory does not exist or path is an empty string. 

128 5.2. 1.5 Cross-References 

129 getcwdi), 5.2.2. 
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130 

131 

132 

133 

134 


136 

137 

138 

139 

140 

141 

142 

143 

I 

144 

146 

146 

147 

148 

149 

160 

151 

162 

163 

154 

156 


5.2.2 Get Working Directory Pathname 

Function: getcwd{) 


5.2.2. 1 Synopsis 

char *getcwd(char *buf, size_t size); 

5.2.2.2 Description 

The getcwdi) function copies an absolute pathname of the current working direc- 
tory to the array of char pointed to by the argument buf and returns a pointer to 
the result. The size argument is the sizfe in bytes of the array of char pointed to 
by the buf argument. If buf is a NULL pointer, the behavior of getcwd 0 is 
undefined. 

5.2.2.3 Returns 

If successful, the buf argument is returned. A NULL pointer is returned if an 
error occurs and the variable errno is set to indicate the error. The contents of buf 
after an error are undefined. 

5.2.2.4 Errors 

If any of the following conditions occur, the getcwdO function shall return a value 
of NULL and set errno to the corresponding value: 



[EINVAL] The size argument is zero. 

[ERANGE] The size argument is greater than zero but smaller than the 
length of the pathname plus 1. 

For each of the following conditions, if the condition is detected, the getcwdO func- 
tion shall return a value of NULL and set errno to the corresponding value: 

[EACCES] Read or search permission was denied for a component of the 
pathname. 

5.2.2.5 Cross-References 
chdirQ, 5.2.1. 
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156 5.3 General File Creation 


157 5.3.1 Open a File 

168 Function: open ( ) 


159 5.3. 1.1 Synopsis 

160 linclude <sys/types . h> 

161 linclude <sy 3 / 3 tat.h> 

162 linclude <fcntl.h> 

163 int open (const char *path, int oflag , . 


164 5.3. 1.2 Description 

165 The openO function establishes the connection between a file and a file descriptor 

tee It creates an open file description that refers to a file and a file descriptor that 

167 refers to that open file description. The file descriptor is used by other I/O func- 

168 lions to refer to that file. The path argument points to a pathname naming a file. 

169 The openO function shall return a file descriptor for the named file that is the 

no lowest file descriptor not currently open for that process. The open file description 

171 is new, and therefore the file descriptor does not share it with any other process 

172 ™ ™ syatem ' The file ofTset 3ha11 be set to the beginning of the file. The 

173 FD_CLOEXEC file descriptor flag associated with the new file descriptor shall be 

174 beared. The file status flags and file access modes of the open file description 

176 Shall be set according to the value of oflag. The value of oflag is the bitwise 

176 inclusive OR of values from the following list. See 6 . 5.1 for the definitions of the 

177 symbolic constants. Applications shall specify exactly one of the first three values 

178 (hie access modes) below in the value of oflag: 

179 0 _RDONLY Open for reading only, 

iso 0 _WRONLY Open for writing only. 

isi 0 _RDWR Open for reading and writing. The result is undefined if this 

182 flag is applied to a FIFO. 

183 Any combination of the remaining flags may be specified in the value of oflag: 

184 0 _APPEND If set, the file offset shall be set to the end of the file prior to 

186 each write. 

186 0 _CREAT This option requires a third argument, mode, which is of type 

187 mode_t . If the file exists, this flag has no effect, except as noted 

188 under 0 _EXCL, below. Otherwise, the file is created; the file’s 

189 user ID shall be set to the effective user ID of the process; the 

190 file s group ID shall be set to the group ID of the directory in 

191 which the file is being created or to the effective group ID of the 

192 process. The file permission bits (see 5 . 6 . 1 ) shall be set to the 

193 value of mode except those set in the file mode creation mask of 

194 th e process (see 5 . 3 . 3 ). When bits in mode other than the file 

196 permission bits are set, the effect is unspecified. The mode \ 
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196 argument does not affect whether the file is opened for reading, 

197 for writing, or for both. 

198 0 _EXCL If 0 _EXCL and 0 _CREAT are set, open 0 shall fail if the file 

, 99 exists. The check for the existence of the file and the creation of 

200 the file if it does not exist shall be atomic with respect to other 

201 processes executing openO naming the same filename in the 

202 same directory with 0 _EXCL and 0 „CREAT set. If 0 _EXCL is 

203 set and 0 _CREAT is not set, the result is undefined. 

204 O NOCTTY If set, and path identifies a terminal device, the open ( ) function 

205 shall not cause the terminal device to become the controlling 

206 terminal for the process (see 7 . 1 . 1 . 3 ). 

207 0 _NONBLOCK 

208 ( 1 ) When opening a FIFO with 0 _RD 0 NLY or 0 _WR 0 NLY set: 

209 (a) If CMTONBLOCKis set: 

21 0 An 'openO for reading-only shall return without 

2n delay. An openO for writing-only shall return an 

212 error if no process currently has the file open for 

213 reading. 

214 (b) IfO_NONBLOCKis clear: 

2,5 An open ( ) for reading-only shall block until a process 

21 6 opens the file for writing. An openO for writing-only 

21 7 ' shall block until a process opens the file for reading. 

21 8 ( 2 ) When opening a block special or character special file that 

219 supports nonblocking opens: 

220 (a) If 0 _N 0 NBL 0 CKis set: 

221 The openO shall return without waiting for the dev- 

222 ice to be ready or available. Subsequent behavior of 

223 the device is device-specific. 

224 (b) If OlNONBLOCK is clear: 

225 The openO shall wait until the device is ready or 

226 available before returning. 

227 ( 3 ) Otherwise, the behavior of 0 _N 0 NBL 0 CK is unspecified. 

228 0 _TRUNC If the file exists and is a regular file, and the file is successfully 

229 opened 0 _RDWR or 0 _WR 0 NLY, it shall be truncated to zero 

230 length and the mode and owner shall be unchanged by this 

231 function call. O.TRUNC shall have no effect on FIFO special 

232 files or terminal device files. Its effect on other file types is 

233 implementation defined. The result of using 0 _TRUNC with 

234 0 _RDONLY is undefined. 

236 If 0 _CREAT is set and the file did not previously exist, upon successful completion 

236 the openO function shall mark for update the stjitime, st_ctime, and stjntime 

237 fields of the file and the st_ctime and stjntime fields of the parent directory. 
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If 0_TRUNC is set and the file did previously exist, upon successful completion 
the open ( ) function shall mark for update the st_ctime and stjntime fields of the 
file. 

5.3. 1.3 Returns 

Upon successful completion, the function shall open the file and return a nonne- 
gative integer representing the lowest numbered unused file descriptor. Other- 
wise, it shall return -1 and shall set errno to indicate the error. No files shall be 
created or modified if the function returns —1. 


246 5.3. 1.4 Errors 

247 If any of the following conditions occur, the open( ) function shall return -1 and set 

248 errno to the corresponding value: 

249 [EACCESJ Search permission is denied on a component of the path prefix, 

250 or the exists and the permissions specified by oflag are 

251 denied, or the file does not exist and write permission is denied 

252 for ^e parent directory of the file to be created, or 0_TRUNC is 

263 specified and write permission is denied. 

254 [EEXIST] 0_CREAT and 0_EXCL are set and the named file exists. 

255 [EINTRJ The open() operation was interrupted by a signal. 

266 [EISDIR] The named file is a directory, and the oflag argument specifies 

267 write or read/write access. 

258 [EMFILE] Too many file descriptors are currently in use by this process. 

259 [ENAMETOOLONG] 

260 Th e length of the path string exceeds (PATH_MAX), or a path, 
name component is longer than (NAME MAX) while 

262 LPOSIX^NO_TRUNC) is in effect. 

263 [ENFILE) Too many files are currently open in the system. 

264 [ENOENT] 0_CREAT is not set and the named file does not exist, or 

0_CREAT is set and either the path prefix does not exist or the 

266 path argument points to an empty string. 

267 [ENOSPC] The directory or file system that would contain the new file can- 

268 \ not be extended. 

269 (ENOTDIR) A component of the path prefix is not a directory. 

270 [ENXIO] 0_NONBLOCK is set, the named file is a FIFO, 0_WR0NLY is 

271 set . and no process has the file open for reading. 

272 [EROFS] The named file resides on a read-only file system and either 

l] 0_WRONLY, 0_RDWR, 0_CREAT (if the file does not exist), or 

0_TRUNC is set in the oflag argument. 
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275 5.3.1.5 Cross-References 

276 close (), 6.3.1; creofO, 5.3.2; dup(), 6.2.1; exec, 3.1.2; fcntlO, 6.5.2; <fcntl.h>, 

277 6.5.1; IseekO, 6.5.3; readO, 6.4.1; <signal.h>, 3.3.1; statO, 5.6.2; 

278 <sys/ stat .h>, 5.6.1; writel ), 6.4.2; umask 0, 5.3.3, 3.3. 1.4. 

279 5.3.2 Create a New File or Rewrite an Existing One 

280 Function: creat () 

i 

281 5.3.2.1 Synopsis 

282 #include <sys/type3 -h> 

283 #include <sys/stat.h> 

284 (include <fcntl.h> 

285 int creat (const char *path, mode_t mode); 

286 5.3.2.2 Description 

287 The function call: 

288 creat (path, mode) ; 

289 is equivalent to: 

290 open (path, o_wronly | 0_creat | 0_TR0NC, mode); 

291 5.3.2.3 Cross-References 

292 openO, 5.3.1; <sys/stat .h>, 5.6.1. 

293 5.3.3 Set File Creation Mask 

294 Function: umasl r() 

295 5.3.3.1 Synopsis 

296 (include <3ys/types . h> 

297 (include <3ys/stat.h> 

298 mode_t umask (mode_t cmask) ; 

299 5.3.3.2 Description 

300 The umask () routine sets the file mode creation mask of the process to cmask and 

301 returns the previous value of the mask. Only the file permission bits (see 5.6.1) of 

302 cmask are used; the meaning of the other bits is implementation defined. 

303 The file mode creation mask of the process is used during open (), creat 0, nikdiri ), 

304 and mkfifol ) calls to turn off permission bits in the mode argument supplied. Bit 
306 positions that are set in cmask are cleared in the mode of the created file. 
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306 5.3. 3. 3 Returns 

307 The file permission bits in the value returned by umask () shall be the previous 
3oa value of the file mode creation mask. The state of any other bits in that value is 

309 unspecified, except that a subsequent call to umask () with that returned value as 

310 cmask shall leave the state of the mask the same as its state before the first call 

311 including any unspecified (by this part of ISO/XEC 9945) use of those bits. 

312 S.3.3.4 Errors 

313 The umask () function is always successful, and no return value is reserved to 

314 indicate an error. 

315 5.S.3.5 Cross-References 

316 chmodi), 5.6.4; creatO, 5.3.2; mkdir(), 5.4.1; mkfifoi), 5.4.2; open() , 5 3 1- 

317 <sys/stat.h>, 5.6.1. 

3is 5.3.4 Link to a Pile 

319 Function: link() 

320 5.3.4.1 Synopsis 

321 int link (const char •existing, const char •new); 

322 5.3.4.2 Description 

323 The argument existing points to a pathname naming an existing file. The argu- I 

324 ment new points to a pathname naming the new directory entry to be created. I 

326 Implementations may support linking of files across file systems. The linkO func- 

326 tion shall atomically create a new link for the existing file and increment the link 

327 count of the file by one. 

328 If the linkO function fails, no link shall be created, and the link count of the file 

329 shall remain unchanged by this function call. 

™ The exlstm S argument shall not name a directory unless the user has appropriate I 

331 privileges and the implementation supports using linkO on directories. 

332 The implementation may require that the calling process has permission to access 

333 the existing file. 

IZ ST S f r«f e ° mpIe ‘ ion . the IMO function shall mark for update the stjitime 
, field ” the file ' Also ’ the s'-ctime and st_mtime fields of the directory that con- 
336 tains the new entry are marked for update. 
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Upon successful completion, link () shall return a value of zero. Otherwise, a 
value of-1 is returned and errno is set to indicate the error. 


340 5.3.4.4 Errors 

341 If any of the following conditions occur, the linkO function shall return -1 and set 

342 errno to the corresponding value: 

343 [EACCES] A component of either path prefix denies search permission; or 

34 ; the requested link requires writing in a directory with a mode 

345 that denies write permission; or the calling process does not 

34 6 have permission to access the existing file, and this is required 

347 by the implementation. 

348 [EEXIST] The link named by new exists. I 

349 [EML1NK] The number of links to the file named by existing would exceed 

350 (LINKJ4AX). 

361 [ENAMETOOLONG] , wiV . . 

352 The length of the existing or new string exceeds (PATHJV 1 AXJ, | 

353 or a pathname component is longer than (NAME_MAX) while 

354 (_POSIX_NO_TRUNC) is in effect. 

355 [ENOENT] A component of either path prefix does not exist, the file named 

355 by existing does not exist, or either existing or new points to an | 

367 empty string. 

368 [ENOSPC] The directory that would contain the link cannot be extended. 

369 [ENOTDIR] A component of either path prefix is not a directory. 

360 [EPERM] The file named by existing is a directory, and either the calling | 

35 ! process does not have appropriate privileges or the implemen- 

362 tation prohibits-using linkO on directories. 

363 [EROFS] The requested link requires writing in a directory on a read- 

364 only file system. 

366 [EXDEV] The link named by new and the file named by existing are on | 

356 different file systems, and the implementation does not support 

367 links between file systems. 


renameO, 5 . 5 . 3 ; unlink 0 , 5 . 5 . 1 . 
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370 5.4 Special File Creation 

371 5.4.1 Make a Directory 

372 Function: mkdirO 

373 5.4.1. 1 Synopsis 

374 #include <sys/type3 . h> 

375 iinclude <sys/stat.h> 

376 int mkdir (const char *path, mode_t mode); | 

377 5.4.1.2 Description 

378 The mkdirO routine creates a new directory with name path. The file permission 

379 bits of the new directory are initialized from mode . The file permission bits of the 

380 mode argument are modified by the file creation mask of the process (see 5.3.3). 

381 When bits in mode other than the file permission bits are set, the meaning of 

382 these additional bits is implementation defined. 

383 The owner ID of the directory is set to the effective user ID of the process. The 

384 directory’s group ID shall be set to the group ID of the directory in which the direc- 

386 tory is being created or to the effective group ID of the process. 

386 The newly created directory shall be an empty directory. 

387 Upon successful completion, the mkdirO function shall mark for update the 

388 stjitime, st_ctime, and stjntime fields of the directory. Also, the st_ctime and 

389 st_mtime fields of the directory that contains the new entry are marked for 

390 update. 

391 5.4. 1.3 Returns 

392 A return value of zero indicates success. A return value of -1 indicates that an 

393 error has occurred, and an error code is stored in errno. No directory shall be 

394 created if the return value is -1. 

396 5.4. 1.4 Errors 

396 If any of the following conditions occur, the mkdirO function shall return -1 and 

397 set errno to the corresponding value: 

398 [EACCES] Search permission is denied on a component of the path prefix, 

399 or write permission is denied on the parent directory of the 

400 directory to be created. 

401 [EEXIST] The named file exists. 

402 [EMLINK] The link count of the parent directory would exceed 

403 (LINK.MAX). 
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[ENAMETOOLONG] 


The length of the path argument exceeds (PATH_MAX), or a 
pathname component is longer than (NAME_MAX) while 
{_POSIX_NO_TRUNCl is in effect. 

A component of the path prefix does not exist, or the path argu- 
ment points to an empty string. 

The file system does not contain enough space to hold the con- 
tents of the new directory or to extend the parent directory of 
the new directory. 

A component of the path prefix is not a directory. 

The parent directory of 1 the directory being created resides on a 
read-only file system. 


[ENOENT] 


[ENOSPC1 


[ENOTDIR1 

[EROFS] 


416 5.4.1.5 Cross-References 


417 chmodO, 5.6.4; statO, 5.6.2; <sys/stat ,h>, 5.6.1; umask (), 5.3.3. 


418 5.4.2 Make a FIFO Special File 

419 Function: mkfifoO 


420 5.4.2.1 Synopsis 


421 #include <sys/types .h> 

422 #include <sys/stat.h> 

423 int mkfifo (const char *path, mode_t mode) 


424 5.4.2.2 Description 

425 The mkfifoO routine creates a neyv FIFO special file named by the pathname 

426 pointed to by path. The file permission bits of the new FIFO are initialized from 

427 mode. The file permission bits of the mode argument are modified by the file crea- 

428 tion mask of the process (see 5.3.3). When bits in mode other than the file permis- 

429 sion bits are set, the effect is implementation defined. 

430 The owner ID of the FIFO shall be set to the effective user ID of the process. The 

431 group ID of the FIFO shall be set to the group ID of the directory in which the FIFO 

432 is being created or to the effective group ID of the process. 

433 Upon successful completion, the mkfifoO function shall mark for update the 

434 stjitime, stjitime, and stjntime fields of the file. Also, the stjitime and stjntime 

435 fields of the directory that contains the new entry are marked for update. 


436 5.4.2.3 Returns 


Upon successful completion, a value of zero is returned. Otherwise, a value of 1 
is returned, no FIFO is created, and errno is set to indicate the error. 
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439 5.4.2.4 Errors 

440 If any of the following conditions occur, the mkfifoO function snail return -1 and 

441 set errno to the corresponding value: 

442 [EACCES1 Search permission is denied on a component of the path prefix, | 

443 or write permission is denied on the parent directory of the file I 

444 to be created. I 

446 (EEXISTl The named file already exists. 

446 | EN AM ETOOLONG] 

447 The length of the path string exceeds (PATH_MAX), or a path- 

44fi name component is longer than (NAME_MAX) while 

449 LPOSIX_NO_TRUNC) is in effect. 

460 [ENOENT] A component of the path prefix does not exist, or the path argu- 

451 ment points to an empty string. 

452 [ENOSPC] The directory that would contain the new file cannot be 

453 extended, or the file system is out of file allocation resources. 

454 (ENOTDIR1 A component of the path prefix is not a directory. 

466 [EROFS1 The named file resides on a read-only file system. 

466 5.4.2.5 Cross-References 

467 chmod(), 5.6.4; exec, 3. 1.2; piped, 6.1.1; stat(), 5.6.2; <sys/stat . h> 5 6 1- 

468 umask (), 5.3.3. ’ 


469 5.5 File Removal 

460 5.5.1 Remove Directory Entries 

461 Function: unlink () 

462 5.5.1. 1 Synopsis 

463 int unlink (const char *path ) ; 

464 5.5. 1.2 Description 

466 The unlinkO function shall remove the link named by the pathname pointed to by 

466 path and decrement the link count of the file referenced by the link. 

467 When the link count of the file becomes zero and no process has the file open the 

468 space occupied by the file shall be freed and the file shall no longer be accessible 

469 If °ne <> r more processes have the file open when the last link is removed, the link 

470 shall be removed before unlink ( ) returns, but the removal of the file contents shall 

471 be postponed until all references to the file have been closed. 
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The path argument shall not name a directory unless the process has appropriate 
privileges and the implementation supports using unlinkO on directories. Appli- 
cations should use rmdirO to remove a directory. 

Upon successful completion, the unlinkO function shall mark for update the 
st_ctime and st_mtime fields of the parent directory. Also, if the link count of the 
file is not zero, the st_ctime field of the file shall be marked for update. 


5.5.1.3 Returns 


Upon successful completion, a value of zero shall be returned. Otherwise, a value 
of -1 shall be returned and errno shall be set to indicate the error. If -1 is 
returned, the named file shall not be changed by this function call, 


482 5.5.1.4 Errors 


If any of the following conditions occur, the unlink () function shall return -1 and 
set errno to the corresponding value: 

[EACCES] Search permission is denied for a component of the path prefix, 
or write permission is denied on the directory containing the 
link to be removed. 

[EBUSY] The directory named by the path argument cannot be unlinked 
because it is being used by the system or another process and 
the implementation considers this to be an error. 

[ENAM ETOOLONG] 

The length of the path argument exceeds (PATHJdAX), or a 
pathname component is longer than (NAME_MAX) while 
(_POSIX_NO_TRUNC) is in effect. 

[ENOENT] The named file does not exist, or the path argument points to 
an empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The file named by path is a directory, and either the calling 
process does not have appropriate privileges or the implemen- 
tation prohibits using unlink () on directories. 

[EROFS] The directory entry to be unlinked resides on a read-only file 
system. 


504 close (), 6.3.1; link 0, 5.3.4; openO, 5.3.1; rename 0, 5.5.3; rmdirO, 5.5.2. 
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606 5.5.2 Remove a Directory 

606 Function: rmdir( ) 

607 5.5.2. 1 Synopsis 

608 int rmdir (const char *path) ; 

609 5.5.2.2 Description 

6 10 The rmdir () function removes a directory whose name is given by path. The 

6 11 directory shall be removed only if it is an empty directory. 

612 If the named directory is the root directory or the current working directory of any 

613 process, it is unspecified whether the function succeeds or whether it fails and 

614 sets errno to [EBUSY]. 

616 If the link count of the directory becomes zero and no process has the directory 

616 open, the space occupied by the directory shall be freed and the directory shall no 

617 longer be accessible. If one or more processes have the directory open when the 

6is last link is removed, the dot and dot-dot entries, if present, are removed before 

r»i9 rmdir( ) returns and no new entries may be created in the directory, but the direc- 

520 tory is not removed until all references to the directory have been closed. 

521 Upon successful completion, the rmdir{) function shall mark for update the 

522 st_ctime and stjntime fields of the parent directory. 

623 5.5.2.3 Returns 

624 Upon successful completion, a value of zero shall be returned. Otherwise, a value 

525 of -1 shall be returned and errno shall be set to indicate the error. If -1 is 

526 returned, the named directory shall not be changed by this function call. 

627 5.5.2.4 Errors 

628 If any of the following conditions occur, the rmdir() function shall return -1 and 

629 set errno to the corresponding value: 

630 [EACCES1 Search permission is denied on a component of the path prefix, 

631 or write permission is denied on the parent directory of the 

632 directory to be removed. 

633 [EBUSY] The directory named by the path argument cannot be removed 

534 because it is being used by another process and the implemen- 

536 tation considers this to be an error. 

636 [EEXIST] or [ENOTEMPTY] 

637 The path argument names a directory that is not an empty 

638 directory. 

639 [ENAMETOOLONG] 

M0 The length of the path argument exceeds (PATH_MAX), or a 

541 pathname component is longer than [NAME_MAX] while 
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LPOSIX_NO_TRUNC) is in effect. 

The path argument names a nonexistent directory or points to 
an empty string. 

A component of the path is not a directory. 

The directory entry to be removed resides on a read-only file 
system. 

648 S.5.2.5 Cross-References 

649 mkdir ( ), 5 . 4 . 1 ; unlinkQ, 5 . 5 . 1 . 

660 5.5.3 Rename a File 

661 Function: renamed) 

662 5.5.3.1 Synopsis 

653 int rename (const char *old, const char *new ) ; 

554 5.5.3.2 Description 

556 The rename () function changes the name of a file. The old argument points to the 
656 pathname of the file to be renamed. The new argument points to the new path- 

667 name of the file. 

668 If the old argument and the new argument both refer to links to the same existing 
569 file, the rename () function shall return successfully and perform no other action. 

660 If the old argument points to the pathname, of a file that is not a directory, the 

661 new argument shall not point to the pathname of a directory. If the link named 

662 by the new argument exists, it shall be removed and old renamed to new. In this 

663 case, a link named new shall exist throughout the renaming operation and shall 

664 refer either to the file referred to by new or old before the operation began. Write 
666 access permission is required for both the directory containing old and the direc- 

666 tory containing new. 

667 If the old argument points to the pathname of a directory, the new argument shall 

668 not point to the pathname of a file that is not a directory. If the directory named 

669 by the new argument exists, it shall be removed and old renamed to new. In this 

670 case, a link named new shall exist throughout the renaming operation and shall 

671 refer either to the file referred to by new or old before the operation began. Thus, 

672 if new names an existing directory, it shall be required to be an empty directory. 

573 The new pathname shall not contain a path prefix that names old. Write access 

574 permission is required for the directory containing old and the directory contain- 
576 ing new. If the old argument points to the pathname of a directory, write access 

576 permission may be required for the directory named by old, and, if it exists, the 

577 directory named by new . 


642 

643 [ENOENT] 

644 

646 [ENOTDIR] 

646 [EROFS] 

647 



' 
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578 If the link named by the new argument exists and the link count of the file 

679 becomes zero when it is removed and no process has the file open, the space occu- 

580 pied by the file shall be freed and the file shall no longer be accessible. If one or 

sal more processes have the file open when the last link is removed, the link shall be 

582 removed before rename () returns, but the removal of the file contents shall be 

683 postponed until all references to the file have been closed. 

584 Upon successful completion, the rename () function shall mark for update the 

585 stjctime and stjntime fields of the parent directory of each file. 

586 5.5.3.S Returns 

587 Upon successful completion, a value of zero shall be returned. Otherwise, a value 

688 of -1 shall be returned and errno shall be set to indicate the error. If -1 is 

589 returned, neither the file named by old nor the file named by new, if either exists, 

590 shall be changed by this function call. 

591 5.5.3.4 Errors 

If any of the following conditions occur, the rename () function shall return -1 and 
set errno to the corresponding value: 

[EACCES] A component of either path prefix denies search permission, or 
one of the directories containing old or new denies write per- 
missions, or write permission is required and is denied for a 
directory pointed to by the old or new arguments. 

[EBUSY] The directory named by old or new cannot be renamed because 
it is being used by the system or another process and the imple- 
mentation considers this to be an error. 

[EEXIST] or lENOTEMPTY] 

The link named by new is a directory containing entries other 
than dot and dot-dot. 

[EINVALl The new directory pathname contains a path prefix that names 
the old directory. 

[EISDIRl The new argument points to a directory, and the old argument 
points to a file that is not a directory. 

[ENAMETOOLONG] 

The length of the old or new argument exceeds {PATH_MAX}, or 
a pathname component is longer than (NAME_MAX) while 
LPOSIX_NO_TRUNC) is in effect. 

[EMLINK] The file named by old is a directory, and the link count of the 
parent directory of new would exceed {LINK_MAX}. 

[ENOENT] The link named by the old argument does not exist, or either 
old or new points to an empty string. 

[ENOSPC] The directory that would contain new cannot be extended. 
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[ENOTDIR] A component of either path prefix is not a directory, or the old 
argument names a directory and the new argument names a 
nondirectory file. 

[EROFS] The requested operation requires writing in a directory on a 

read-only file system. 

[EXDEV] The links named by new and old are on different file systems, 
and the implementation does not support links between rile 
systems. 


625 5.5.S.5 Cross-References 

\ 

626 link (), 5.3.4; rmdirO, 5.5.2; unlink 0, 5.5.T. 


627 5.G File Characteristics 


5.6.1 File Characteristics: Header and Data Structure 

The header < sy s/stat.h> defines the structure stat which includes the 
members shown in Table 5-1, returned by the functions stat 0 and fstatt). 


Member 

Type 


Member 

Name 


stjxtime 

8t_mtime 

8t_ctime 


„ Table 5-1 - stat Structure 

Description 

File mode (see 5.6. 1.2). 

File serial number. 

ID of device containing this file. 

Number of links. 

User ID of the owner of the file. 

Group ED of the group of the file. 

For regular files, the file size in bytes. For other file types, the use of 
this field is unspecified. 

Time of last access. 

Time of last data modification. 

Time of last file status change. 


NOTE: File serial number and device ID taken together uniquely identify the file within the system. 

All of the described members shall appear in the stat structure. The structure 
members st mode, stjno, st_dev, st_uid, stj;id, st_atime stjttime m ****** 
shall have meaningful values for all file types defined in this part of ISO/IEC 9945. 
The value of the member stnlink shall be set to the number of links to the hie. 
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5.6.1.1 <aya/atat . h> File Types 

The following macros shall test whether a file is of the specified type. The value 
m supplied to the macros is the value of st_mode from a stat structure. The macro 
evaluates to a nonzero value if the test is true, zero if the test is false. 

®-lSDIR(m) Test macro for a directory file. * 


®-lSDIR(/n) Test macro for a directory file. * 
S_ISCHR(m) Test macro for a character special file. 
SjSBLKfm) Test macro for a block special file. 

S JSREG(m) Test macro for a regular file. 

SjSFIFO(m) Test macro for a pipe or a FIFO special file. 


5.6.1.2 <sy«/stat.h> File Modes 

S e e^ m H 0de8 iK P ?? i r n n 0f ValUeS ° f t7Pe m0deJ ’ Such 38 the >* value, are 
bit-encoded with the following masks and bits: 


SJRWXU 


i'*' 

SJRWXG 


S_IRWXO 


S_ISUID 


S_ISGID 


Read, write, search (if a directory), or execute (otherwise) permis- 
sion8 mask for the file owner class. 

SJRUSR Read permission bit for the file owner class. 

S_IWUSR Write permission bit for the file owner class. 

S_IXUSR Search (if a directory) or execute (otherwise) per- 
missions bit for the file owner class. 

Read, write search (if a directory), or execute (otherwise) permis- 
sions mask for the file group class. 

S_IRGRP Read permission bit for the file group class. * 

S_IWGRP Write permission bit for the file group class. 

SjXGRP Search (if a directory) or execute (otherwise) per- 
missions bit for the file group class. 

Read, write search (if a directory), or execute (otherwise) permis- 
sions mask for the file other class. 

S-IROTH Read permission bit for the file other class. 

SJWOTH Write permission bit for the file other class. 

SJXOTH Search (if a directory) or execute (otherwise) per- 
missions bit for the file other class. 

Set user ID on execution. The effective user ID of the process 
shall be set to that of the owner of the file when the file is run as 
a program (see exec). On a regular file, this bit should be cleared 
on any write. 

Set group ID on execution. Set effective group ID on the process to 
the group of the file when the file is run as a program (see exec). 
On a regular file, this bit should be cleared on any write. 
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689 The bits defined by S_IRUSR, SJWUSR, S_IXUSR, SJRGRP, SJWGRP, S_IXGRP, 

690 SJROTH, SJWOTH, SJXOTH, SJSUID, and SJSGID shall be unique. SJRWXU 

691 shall be the bitwise inclusive OR of SJRUSR, SJWUSR, and SJXUSR. S JRWXG 

692 shall be the bitwise inclusive OR of SJRGRP, SJWGRP, and SJXGRP. SJRWXO 

693 shall be the bitwise inclusive OR of SJROTH, SJWOTH, and SJXOTH. Imple- 

694 mentations may OR other implementation-defined bits into SJRWXU, SJRWXG, 

695 and SJRWXO, but they shall not overlap any of the other bits defined in this part 

696 of ISO/IEC 9945. The file permission bits are defined to be those corresponding to 

697 the bitwise inclusive OR of SJRWXU, SJRWXG, and SJRWXO. 

698 5.6.1.3 <»y«/stat.h> Time Entries 

699 The time-related fields of struct stat are as follows: 

700 st_atime Accessed file data, for example, read)). 

701 stjntime Modified file data, for example, write)). 

702 stjctime Changed file status, for example, chmodO 

703 These times are updated as described in 2.3.5. 

704 » 

706 Times are given in seconds since the Epoch. 

706 5.6.1.4 Cross-References 

707 chmodO, 5.6.4; chown (), 5.6.5; creatO, 5.3.2; exec, 3.1.2; link (), 5.3.4; mkdirO, 

708 5.4.1; mkfifoO, 5.4.2; pipeO, 6.1.1; read(), 6.4.1; unlinkO, 5.5.1; utimeO, 5.6.6; 

709 write 0, 6.4.2; removeO [C Standard (2)1. 


710 5.6 .2 Get File Status 

711 Functions: stat 0, f stat () 

712 5.6.2.1 Synopsis 

713 linclude <3ys/types .h> 

714 #include <sys/stat.h> 

715 int stat (const char *path, struct stat *buf) ; 

716 int f stat (int fildes, struct stat *buf ) ; 

717 5.6.2.2 Description 

718 The path argument points to a pathname naming a file. Read, write, or execute 

719 permission for the named file is not required, but all directories listed in the path- 

720 name leading to the file must be searchable. The stat{) function obtains informa- 

721 tion about the named file and writes it to the area pointed to by the buf argument. 

722 Similarly, the fstat( ) function obtains information about an open file known by the 

723 file descriptor fildes . 


I 

I 



5.6 File Characteristics 


103 


ISO/IEC 9945-1: 1990 
IEEE Std 1003.1-1990 


INFORMATION TECHNOLOGY— POSIX 


Part 1: SYSTEM API [C LANGUAGE] 


ISO/IEC 9946-1: 1990 
IEEE Std 1003.1-1990 


724 An implementation that provides additional or alternate file access control 
726 mechanisms may, under implementation-defined conditions, cause the stat() and 

726 fstat () functions to fail. In particular, the system may deny the existence of the 

727 file specified by path . 

728 Both functions update any time-related fields, as described in 2.3.5, before writing 

729 into the stat structure. 

730 The buf is taken to be a pointer to a stat structure, as defined in the header 

731 <sys/ stat . h>, into which information is placed concerning the file. 

732 5.6.2.3 Returns 

733 Upon successful completion, a value of zero shall be returned. Otherwise, a value 

734 of-1 shall be returned and errno shall be set to indicate the error. 


767 5.6.3.2 Description 

768 The accessO function checks the accessibility of the file named by the pathname 

759 pointed to by the path argument for the file access permissions indicated by 

760 amode, using the real user ID in place of the effective user ID and the real group 

761 ID in place of the effective group ID. 

762 The value of amode is either the bitwise inclusive OR of the access permissions to 

763 be checked (R_OK, W_OK, and X_OK) or the existence test (F_OK). See 2.9.1 for 

764 the description of these symbolic constants. 

765 If any access permission is to be checked, each shall be checked individually, as 

766 described in 2.3.2. If the process has appropriate privileges, an implementation 

767 may indicate success for XJ3K even if none of the execute file permission bits are 

768 set. 


736 S.6.2.4 Errors 


736 

737 

738 

739 

740 

741 

742 

743 

744 

746 

746 

747 

748 


If any of the following conditions occur, the stat () function shall return -1 and set 
errno to the corresponding value: 

[EACCES] Search permission is denied for a component of the path prefix. 
[ENAMETOOLONG] 

The length of the path argument exceeds (PATH_MAX), or a 
pathname component is longer than (NAME_MAX) while 
(_POSIX_NO_TRUNC) is in effect. 

[ENOENT] The named file does not exist, or the path argument points to 
an empty string. 

(EN0TDIR1 A component of the path prefix is not a directory. 

If any of the following conditions occur, the fstat () function shall return -1 and set 
errno to the corresponding value: *■ 

[EBADF] The fildes argument is not a valid file descriptor. 


749 5.6.2.5 Cross-References 

750 creat (), 5.3.2; dup(), 6.2.1; fcntlQ, 6.5.2; openO, 5.3.1;pipe(), 6.1.1; 
7fii <sys/stat . h>, 5.6.1. 


752 5.6.3 Check File Accessibility 

753 Function: accessO 

764 5.6.3.1 Synopsis 

755 #include <unistd.h> 

756 int access (const char *path, int amode); 


769 5.6.3.3 Returns 

770 If the requested access is permitted, a value of zero shall be returned. Otherwise, 

771 a value of —1 shall be returned and errno shall be set to indicate the error. 


772 5.6.3.4 Errors 

773 If any of the following conditions occur, the accessO function shall return -1 and 

774 set errno to the corresponding value: 

776 [EACCES] The permissions specified by amode are denied, or search per- 

776 mission is denied on a component of the path prefix. 


777 

778 

779 

780 

781 

782 

783 

784 

785 

786 

787 

788 


[ENAMETOOLONG] 

The length of the path argument exceeds (PATH.MAX), or a 
pathname component is longer than [NAME_MAX] while 
[_POSIXJNfO_TRUNC) is in effect. 

[ENOENT] The path argument points to an empty string or to the name of 
a file that does hot exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EROFS] Write access was requested for a file residing on a read-only file 

system. 

For each of the following conditions, if the condition is detected, the access () func- 
tion shall return -1 and set errno to the corresponding value: 

[EINVAL] An invalid value was specified for amode . 


789 5.6.3.5 Cross-References 

'790 chmodO, 5.6.4; statO, 5.6.2; <unistd . h>, 2.9. 
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791 5.6.4 Change File Modes 

792 Function: chmodi) 

793 5.6.4. 1 Synopsis 

794 #include <sys/types .h> 

795 #include <sys/stat.h> 

796 int chmod (const char *path, mode_t mode); 

797 5.6.4.2 Description 

798 The path argument shall point to a pathname naming a file. If the effective user 

799 ID of the calling process matches the file owner or the calling process has 

boo appropriate privileges, the chmodi) function shall set the S_ISUID, S.ISGID, and 

aoi the file permission bits, as described in 5 . 6 . 1 , of the named file from the 

802 corresponding bits in the mode argument. These bits define access permissions 

bos for the user associated with the file, the group associated with the file, and all oth- 

804 ers, as described in 2 . 3 . 2 . Additional implementation-defined restrictions may 

bos cause the S_ISUID and S_ISGID bits in mode to be ignored. 

806 If the calling process does not have appropriate privileges, if the group ID of the 

807 file does not match the effective group ID or one of the supplementary group IDs, 

808 and if the file is a regular file, bit S_ISGID (set group ID on execution) in the mode 

809 of the file shall be cleared upon successful return from chmodi). 

sio The effect on file descriptors for files open at the time of the chmodi ) function is 
an implementation defined. 

812 Upon successful completion, the chmodi) function shall mark for update the 

813 stjctime field of the file. 

814 5.6.4.3 Returns 

sis Upon successful completion, the function shall return a value of zero. Otherwise, 

816 a value of -1 shall be returned and errno shall be set to indicate the error. If — 1 is 

817 returned, no change to the file mode shall have occurred. 


818 5.6.4.4 Errors 

819 If any of the following conditions occur, the chmodi) function shall return -1 and 

820 set errno to the corresponding value: 

821 [EACCES 1 Search permission is denied on a component of the path prefix. 

822 [ENAMET 00 L 0 NG 1 

823 The length of the path argument exceeds {PATH_MAX}, or a 

824 pathname component is longer than {NAME_MAX} while 

825 UPOSIX_NO_TRUNC} is in effect. 

826 [ENOTDIR] A component of the path prefix is not a directory. 
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827 [ENOENT] The named file does not exist or the path argument points to an 

828 empty string. 

829 [EPERM] The effective user ID does not match the owner of the file, and 

830 the calling process does not have the appropriate privileges. 

831 [EROFS] The named file resides on a read-only file system. 

832 5.6.4.5 Cross-References 

833 chownO, 5 . 6 . 5 ; mkdirO, 5 . 4 . 1 ; mkfifo (), 5 . 4 . 2 ; statO, 5 . 6 . 2 ; <sys/stat . h>, 5 . 6 . 1 . 

834 5.6.5 Change Owner and Group of a File 

835 Function: chowni) 

836 5.6.5. 1 Synopsis 

837 #include <sys/types .h> 

838 int chown (const char *path, uid_t owner, gid_t group); 

839 5.6.5.2 Description 

840 The path argument points to a pathname naming a file. The user ID and group ID 

841 of the named file are set to the numeric values contained in owner and group 

842 respectively. 

843 Only processes with an effective user ID equal to the user ID of the file or 

844 with appropriate privileges may change the ownership of a file. If 
846 LPOSIX^CHOWN.RESTRICTED) is in effect for path : 

846 ( 1 ) Changing the owner is restricted to processes with appropriate 

847 privileges. 

848 ( 2 ) Changing the group is "permitted to a process without appropriate 

849 privileges, but with an effective user ID equal to the user ID of the file, if 

850 and only if owner is equal to the user ID of the file and group is equal 

86 1 either to the effective group ID of the calling process or to one of its sup- 

862 plementary group IDs. 

853 If the path argument refers to a regular file, the set-user-ID (SJSUID) and set- 

854 group-ID (S.ISGID) bits of the file mode shall be cleared upon successful return 
856 from chowni ), unless the call is made by a process with appropriate privileges, in 
856 which case it is implementation defined whether those bits are altered. If the 

867 chowni) function is successfully invoked on a file that is not a regular file, these 

868 bits may be cleared. These bits are defined in 5 . 6 . 1 . 

859 Upon successful completion, the chowni) function shall mark for update the 

860 stjctime field of the file. 
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! 

I 
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861 5.6. 5.3 Returns 

862 Upon successful completion, a value of zero shall be returned. Otherwise, a value 

863 of -1 shall be returned and errno shall be set to indicate the error. If -1 is 

864 returned, no change shall be made in the owner and group of the file. 


866 5.6.5.4 Errors 


866 

867 

868 

869 

870 

871 

872 


874 

876 

876 

877 

878 

879 

880 

881 

882 

883 

884 


If any of the following conditions occur, the chownO function shall return -1 and 
set errno to the corresponding value: 

[EACCES] Search permission is denied on a component of the path prefix. 

[ENAMETOOLONG] 

The length of the path argument exceeds (PATH_MAX), or a 
pathname component is longer than (NAME.MAX) while 
LPOSIX_NO_TRUNC) is in effect. 

TENOTDIRJ A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist, or the path argument points to 
an empty string. 

[EPERM] The effective user ID does not match the owner of the file, or the 
calling process does not have appropriate privileges and 
(_POSIX_CHOWN_RESTRICTED) indicates that such privilege is 
required. 

[EROFS] The named file resides on a read-only file system. 

For each of the following conditions, if the condition is detected, the chowni) func- 
tion shall return —1 and set errno to the corresponding value: 

[EINVAL] The owner or group ID supplied is invalid and not supported by 
the implementation. 


886 5.6.5.5 Cross-References 

886 chmod () , 5.6.4; <sys/stat . h>, 5.6.1. 


887 5.6.6 Set File Access and Modification Times 

888 Function: utime () 

889 5.6.6.1 Synopsis 

890 # include <sys/types . h> 

891 #include <utime.h> 

892 int utime (const char *path, const struct utimbuf Himes); 
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893 5.6.6.2 Description 

894 The argument path points to a pathname naming a file. The utimet ) function sets 

895 the access and modification times of the named file. 

896 If the times argument is NTJLL, the access and modification times of the file are 

89? set to the current time. The effective user ID of the process must match the owner 

898 of the file, or the process must have write permission to the file or appropriate 

899 privileges, to use the utime 0 function in this manner. 

900 If the times argument is not NULL, it is interpreted as a pointer to a utimbuf 

901 structure, and the access and modification times are set to the values contained in 

902 the designated structure. Only the owner of the file and processes with appropri- 

903 ate privileges shall be permitted to use 'the utime 0 function in this way. 

904 The utimbuf structure is defined by the header <utime .h> and includes the fol- 
906 lowing members: 


906 

907 

908 

909 



Member 

Name 

actime 

modtime 


Description 

Access time 
Modification time 


910 The times in the utimbuf structure are measured in seconds since the Epoch. 

911 Implementations may add extensions as permitted in 1.3.1.1, point (2). Adding j 

912 extensions to this structure, which might change the behavior of the application 

913 with respect to this standard when those fields in the structure are uninitialized, 

914 also requires that the extensions be enabled as required by 1.3. 1.1. 

915 Upon successful completion, the utimet) function shall mark for update the 

916 stjctime field of the file. 


917 S.6.6.3 Returns 

9is Upon successful completion, the'function shall return a value of zero. Otherwise, 
i 919 a value of-1 shall be returned, errno is set to indicate the error, and the file times 
920 shall not be affected. 


921 5.6.6.4 Errors 

922 If any of the following conditions occur, the utime 0 function shall return -1 and 

923 set errno to the corresponding value: 

924 [EACCES] Search permission is denied by a component of the path prefix, 

925 or the times argument is NULL and the effective user ID of the 

926 process does not match the owner of the file and write access is 

927 denied. 

928 [ENAMETOOLONG] 

929 The length of the path argument exceeds (PATH_MAX), or a 

930 pathname component is longer than (NAME_MAX) while 

931 {_POSIX_NO_TRUNC} is in effect. 
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932 

933 

[ENOENT] 

The named file does not exist or the path argument points to an 
empty string. 

934 

[ENOTDIR] 

A component of the path prefix is not a directory. 

936 

936 

937 

938 

[EPERM] 

The times argument is not NULL, the effective user ID of the 
calling process has write access to the file, but does not match 
the owner of the file, and the calling process does not have the 
appropriate privileges. 

939 

[EROFS] 

The named file resides on a read-only file system. 


940 5.6.6.5 Cross-References 

941 <sys/stat.h>, 5.6.1. 


M 2 5.7 Configurable Pathname Variables 
M3 5.7.1 Get Configurable Pathname Variables 

844 Functions: pathconfO, fpathconfO 

ms 5.7.1. 1 Synopsis 

M6 tinclude <unistd.h> 

947 long pathconf (const char •path, int name); | 

948 long fpathconf (int fildes, int name); 

949 5.7.1.2 Description 

951 deteZlnTth ) fp f hc ° nf{ )fun cti°ns provide a method for the application to 

~ i*s.” tzs; “ " op ‘“ >“ » 

“ ssssisssss 

956 dhectorT a -;f lmen V epre f? tS th t v f riable t0 be queried relative to that file or 

957 Tahlp 5 9 d implementation shall support all of the variables listed in 

958 IiiLi t n “ may 8UpP ° rt ° thers - The variables in Table 5-2 come from 

959 Cunistd h> tw <u ^ std - h> and the symbolic constants, defined in 
cunistd . h>, that are the corresponding values used for name. 

960 5.7.1.3 Returns 

2 rLurn m -l. iS “ inVaU<1 ^ ** pathcon ^ “ d fpathconfO functions shall 

2 IS ™ P ®“ din |, t ? name bas no limit for the path or file descriptor, 
he pathconf ( ) and fpathconfi ) functions shall return -1 without changing errno . 
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Table 5-2 - Configurable Pathname Variables 


967 

Variable 

name Value 

Notes 

968 

(LINK.MAX) 

LPC_UNK_MAX) 

(i) 

969 

(MAX_CANON) 

(_PC_MAX_CANON) 

(2) 

970 

(MAXJNPUT) 

LPC.MAXJNFUTl 

(2) 

971 

(NAME.MAX) 

(_PC_NAME_MAX) 

(3), (4) 

972 

IPATH.MAX] 

(_PC_PATH_MAX) 

(4), (5) 

973. 

(PIPE_BUF) 

LPC_PIPE_BUF) 

(6) 

974 

LPOSIX_CHOWN_KESTRICTEDI 

(_PC_CH0WN_RESTR1CTED) 

(7) 

976 

LPOSIX_NO_TRUNC) 

(_PC_NO_TRUNC) 

(3,4) 

976 

(_POSIX_VDISABLE) 

LPC.VDISABEE) 

(2) 


(1) If path or fildes refers to a directory, the value returned applies to the directory itself. 

(2) If path or fildes does not refer to a terminal file, it is unspecified whether an implementation 
supports an association of the variable name with the specified file. 

(3) If path or fildes refers to a directory, the value returned applies to the filenames within the 
directory. 

(4) If path or fildes does not refer to a directory, it is unspecified whether an implementation 
supports an association of the variable name with the specified file. 

(5) If path or fildes refers to a directory, the value returned is the maximum length of a relative 
pathname when the specified directory is the working directory. 

(6) If path refers to a FIFO, or fildes refers to a pipe or a FIFO, the value returned applies to the 
referenced object itself. If path or fildes refers to a directory, the value returned applies to 
any FIFOs that exist or can be created within the directory. If path or fildes refers to any 
other type of file, it is unspecified whether an implementation supports an association of the 
variable name with the specified file. 

(7) If path or fildes refers to a directory, the value returned applies to any files defined in this 
part of ISOAEC 9945, other than directories, that exist or can be created within the 
directory. 


If the implementation needs to use path to determine the value of name and the 
implementation does not support the association of name with the file specified by 
path , or if the process did not have the appropriate privileges to query the file 
specified by path , or path does not exist, the pathconfO function shall return -1. 

If the implementation needs to use fildes to determine the value of name and the 
implementation does not support the association of name with the file specified by 
fildes , or if fildes is an invalid file descriptor, the fpathconfO function shall 
return -1. 

Otherwise, the pathconfO and fpathconfO functions return the current variable 
value for the file or directory without changing errno. The value returned shall 
not be more restrictive than the corresponding value described to the application 
when it was compiled with the implementation’s <limits .h> or cunistd. h>. 
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iooh 5 . 7 . 1.4 Errors 

1009 If any of the following conditions occur, the pathconfi) and fpathconfi) functions 

1010 shall return -1 and set errno to the corresponding value: 

ion [EINVAL] The value of name is invalid. 

1012 For each of the following conditions, if the condition is detected, the pathconfO 

1013 function shall return -1 and set errno to the corresponding value: 

ion [EACCES 1 Search permission is denied for a component of the path prefix. 

1016 [EINVAL 1 The implementation does not support an association of the vari- 

1016 able name with the specified file. 

1017 [ENAMETOOLONG] 

The length of the path argument exceeds (PATH_MAX), or a 
, ’ pathname component is longer than (NAME_MAX) while 

1020 LPOSI 3 f_NO_TRUNC) is in effect. 

1021 [ENOENT] The named file does not exist, or the path argument points to 

1022 an empty string. 

1023 [ENOTDIR] A component of the path prefix is not a directory. 

1024 For each of the following conditions, if the condition is detected, the fpathconfi) 
1026 function shall return -1 and set errno to the corresponding value: 

1026 [EBADF] The fildes argument is not a valid file descriptor. 

1027 [EINVAL] The implementation does not support an association of the vari- 

1025 able name with the specified file. 
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Section 6: Input and Output Primitives 


1 The functions in this section deal with input and output from files and pipes. | 

2 Functions are also specified that deal with the coordination and management of 

3 file descriptors and I/O activity. 


4 6.1 Pipes 

5 6.1.1 Create an Inter- Process Channel 

6 Function: pipe () 

\ 6.1. 1.1 Synopsis 

8 int pipe(int fildes [ 2 ]); I 

9 6.1. 1.2 Description 

10 The pipe () function shall create a pipe and place two file descriptors, one each into 

11 the arguments fildes[ 0 ] and fildesil], that refer to the open file descriptions for 

12 the read and write ends of the pipe. Their integer values shall be the two lowest 

13 available at the time of the pipe () function call. The 0 _NONBLOCK and | 

14 FD_CLOEXEC flags shall be clearjm both file descriptors. IThe fcntli) function | 

15 can be used to set these flags.] I 

16 Data can be written to file descriptor fildes[ 1 ] and read from file descriptor 

17 fildes[ 0 ]. A read on file descriptor fildes[ 0 ] shall access the data written to file 
is descriptor fildesil] on a first-in-first-out basis. 

19 A process has the pipe open for reading if it has a file descriptor open that refers 

20 to the read end, fildesl 0 ]. A process has the pipe open for writing if it has a file 

21 descriptor open that refers to the write end, fildesl U- 

22 Upon successful completion, the pipe () function shall mark for update the 

23 stjatime, stjctime, and st_mtime fields of the pipe. 

24 6.1. 1.3 Returns 

25 Upon successful completion, the function shall return a value of zero. Otherwise, 

26 a value of -1 shall be returned and errno shall be set to indicate the error. 
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6. 1.1. 4 Errors 

If any of the following conditions occur, the pipe() function shall return -1 and set 
errno to the corresponding value: 

[EMFILE] More than {OPEN_MAX}— 2 file descriptors are already in use by 
this process. 

[ENFILE] The number of simultaneously open files in the system would 
exceed a system-imposed limit. 

6. 1.1. 5 Cross-References 

fcntlO , 6.5.2; open( ), 5.3.1; read(), 6.4.1; write (), 6.4.2. 


as 6.2 File Descriptor Manipulation 

37 6.2.1 Duplicate an Open File Descriptor 

38 Functions: dup(), dup2() 

39 6.2.1.1 Synopsis 

40 int dup (int fildes) ; | 

41 int dup2 (int fildes, int fildes2) ; | 

42 6. 2. 1.2 Description 

43 The dup () and dup2() functions provide an alternate interface to the service pro- 

44 vided by the fcntlO function using the F_DUPFD command. The call: 

45 fid = dup (fildes); 

46 shall be equivalent to: 

47 fid = fcntl (fildes, F_DUPFD, 0) ; 

48 The call: 

49 fid = dup2 (fildes, fildes2) ; 

50 shall be equivalent to: 

61 close (filde32); 

52 fid = fcntl (fildes, F_DUPFD, fildes2) ; 

53 except for the following: 

54 (1) \tfildes2 is negative or greater than or equal to (OPEN_MAX), the dup2() \ 

55 function shall return -1 and errno shall be set to [EBADF]. 

56 (2) It fildes is a valid file descriptor and is equal to fildes2, the dup2() func- 

67 ' tion shall return fildes2 without closing it. 
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(3) If fildes is not a valid file descriptor, dup20 shall fail and not close 
fildes2. 

(4) The value returned shall be equal to the value of fildes2 upon successful j 

completion or shall be -1 upon failure. I 

6.2.1.3 Returns 

Upon successful completion, the function shall return a file descriptor. Other- 
wise, a value of-1 shall be returned and errno shall be set to indicate the error. 

6.2.1.4 Errors 

If any of the following conditions occur, the dup () function shall return -1 and set 
errno to the corresponding value; 

[EBADF] The argument fildes is not a valid open file descriptor. 

[EMFILE] The number of file descriptors would exceed (OPEN_MAX). 

If any of the following conditions occur, the dup2() function shall return -1 and 
set errno to the corresponding value; 

[EBADF] The argument fildes is not a valid open file descriptor, or the 
argument fildes2 is negative or greater than or equal to 
10PEN_MAX). 

[EINTR] The dup20 function was interrupted by a signal. I 

6.2.X.5 Cross-References 

closed, 6.3.1; creatd, 5.3.2; exec, 3.1.2; fcntlO, 6.5.2; openO, 5.3.1; piped, 6.1.1. 



6.3 File Descriptor Deassignment 

6.3.1 Close a File 

Function: close 0 

6.3.1.1 Synopsis 

int close (int fildes ); 

6.3.1.2 Description 

The close O function shall deallocate (i.e., make available for return by subsequent 
openOs, etc., executed by the process) the file descriptor indicated by fildes. All 
outstanding record locks owned by the process on the file associated with the file 
descriptor shall be removed (that is, unlocked). 
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s sisasst- 'jSKKfc: * “ 

: 

97 6.3. 1.3 Returns 

: ■ — 

ioo 6.3. 1.4 Errors 

- L\r: ^ h “iz“;zr r - ,h * — «™ -■ »d 

IEBADF] The fildes argument is not a vaUd file descriptor. 

[EINTRJ The close function was interrupted by a signal. 

105 6.3. 1.5 Cross<References 

los 6.4 Input and Output 

109 6.4.1 Read from a File 

no Function: readO 

111 6.4. 1.1 Synopsis 

112 ssize_t readtint fildes, void 'buf, aize_t nbyte ) ; , 

H3 6.4.1.2 Description 

no 1heo£ [™ m y ^ associated with 

no If n6y te is zero, the read() function shall return zero and have no other results 

::: 
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from readO, the file offset shall be incremented by the number of bytes actually 
read. 

On a file not capable of seeking, the read () shall start from the current position. 
The value of a file offset associated with such a file is undefined. 

Upon successful completion, the read ( ) function shall return the number of bytes 
actually read and placed in the buffer. This number shall never be greater than 
nbyte. The value returned may be less than nbyte if the number of bytes left in 
the file is less than nbyte, if the read{ ) request was interrupted by a signal, or if 
the file is a pipe (or FIFO) or special file and has fewer than nbyte bytes immedi- 
ately available for reading. For example, a readO from a file associated with a 
terminal may return one typed line of data. 

If a read () is interrupted by a signal before it reads any data, it shall return -1 
with errno set to [EINTR]. 

If a readO is interrupted by a signal after it has successfully read some data, 
either it shall return -1 with errno set to [EINTR], or it shall return the number of 
bytes read. A readO from a pipe or FIFO shall never return with errno set to 
[EINTR] if it has transferred any data. 

No data transfer shall occur past the current end-of-file. If the starting position is 
at or after the end-of-file, zero shall be returned. If the file refers to a device spe- 
cial file, the result of subsequent readO requests is implementation defined. 

If the value of nbyte is greater than (SSIZE_MAX), the result is implementation | 
defined. " I 

When attempting to read from an empty pipe (or FIFO): 

(1) If no process has the pipe open for writing, readO shall return zero to 
indicate end-of-file. 

(2) If some process has the pipe open for writing and 0_N0NBL0CK is set, 
readO shall return -1 and set errno to [EAGAIN], 

(3) If some process has the pipe open for writing and O_N0NBL0CK is clear, | 

read 0 shall block until some data is written or the pipe is closed by all | 
processes that had the pipe open for writing. | 

When attempting to read a file (other than a pipe or FIFO) that supports non- 
blocking reads and has no data currently available: 

(1) If 0_N0NBL0CK is set, readO shall return -1 and set errno to I EAGAIN]. 

(2) If 0_N0NBL0CK is clear, readO shall block until some data becomes 
available. 

The use of the O_N0NBL0CK flag has no effect if there is some data available. 

For any portion of a regular file, prior to the end-of-file, that has not been written, 
read 0 shall return bytes with value zero. 

Upon successful completion where nbyte is greater than zero, the readO function | 
shall mark for update the st_atime field of the file. I 
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6.4.1.3 Returns 

i«i ofbytes aX^Hy read ^Other^i tom?! I^halT “t integer indicatin B ‘he number 
i «2 to indicate the error and The n r [? < ’TJ Value 0f " 1 and 3et «™> 

163 indeterminate. content of the buffer pointed to by buf is 

164 6.4. 1.4 Errors 

* W ‘b 6 read()fUnCti0n Shal > -turn -1 and set 

169 [EBADF] The^Wes argument is not a valid file descriptor open for 

ill [EINTR] Thread operation was interrupted by a signal, and either no 

SaT^Trl:^ 0 ^ impl “ 0n — - 


The implementation supports job control, the process is in a 


6.4. 1.5 Cross-References 


Si| 7 3 l 2 l] ^ 621; fCntl0 ’ 65 - 2; 6 -5 3; 0 Pen(), 5.3.1 -pipeO, 6.1.1; 


193 6.4.2 Write to a File 

184 Function: write () 

186 6.4.2.1 Synopsis 

186 S3ize_t write tint fildes, 

187 6.4.2.2 Description 


const void *buf, size_t nbyte) , 


bylufTtL^eZ^ buffer polnted t0 

refuibeTnSr 1 ^ ^ ™ ^ 

P 0 ree r d^m 
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fildes. Before successful return from writei), the file offset shall be incremented 
by the number of bytes actually written. On a regular file, if this incremented file 
offset is greater than the length of the file, the length of the file shall be set to this 
file offset. 

On a file not capable of seeking, the write 0 shall start from the current position. 
The value of a file offset associated with such a file is undefined. 

If the 0_APPEND flag of the file status flags is set, the file offset shall be set to the 
end of the file prior to each write, and no intervening file modification operation | 
shall be allowed between changing the file offset and the write operation. | 

If a writei) requests that more bytes be written than there is room for (for exam- 
ple, the physical end of a medium), only as many bytes as there is room for shall 
be written. For example, suppose there is space for 20 bytes more in a file before 
reaching a limit. A write of 512 bytes would return 20. The next write of a 
nonzero number of bytes would give a failure return (except as noted below). 

Upon successful completion, the writei) function shall return the number ofbytes 
actually written to the file associated with fildes. This number shall never be 
greater than nbyte. 

If a writei) is interrupted by a signal before it writes any data, it shall return -1 
with errno set to [EINTR]. 

If writei) is interrupted by a signal after it successfully writes some data, either it 
shall return -1 with errno set to [EINTRJ, or it shall return the number ofbytes 
written. A writei) to a pipe or FIFO shall never return with errno set to [EINTRJ if 
it has transferred any data and nbyte is less than or equal to [PIPE_BUF). 

If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation | 
defined. j 

After a writei) to a regular file has successfully returned: | 

(1) Any successful readi) from each byte position in the file that was | 

modified by that writei) shall return the data specified by the writei) for | 
that position, until such byte positions are again modified. | 

(2) Any subsequent successful writei) to the same byte position in the file | 

shall overwrite that file data. The phrase “subsequent successful writei ) n | 
in the previous sentence is intended to be viewed from a system perspec- | 
tive [i.e., readi) followed by a systemwide subsequent writei)]. 1 

Write requests to a pipe (or FIFO) shall be handled in the same manner as write | 
requests to a regular file, with the following exceptions: j 

(1) There is no file offset associated with a pipe, hence each write request 
shall append to the end of the pipe. 

(2) Write requests of (PIPE_BUF) bytes or less shall not be interleaved with 
data from other processes doing writes on the same pipe. Writes of 
greater than {PIPE_BUF} bytes may have data interleaved, on arbitrary 
boundaries, with writes by other processes, whether or not the 
0_N0NBL0CK flag of the file status flags is set. 
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Z (3) 1 hi 6 ?- K Nf f BL0CK i9 a write request may cause the process 
to block, but on normal completion it shall return nbyte 

z (4) * shau be “ ** 1 

241 (a) The writeO function shall not block the process. 

242 (b) A writ e request for (PIPE_BUF) or fewer bytes shall either: , 

244 f11 [hed-ul !^ um t dent ^ 8pace a u vailable in the P ; P«. transfer all | 

the data and return the number of bytes requested, | 

246 l2i dlteT^T su * de "‘ s P ace avaiiablein the pipe, transfer no | 

data and return -1 with errno set to [EAGAIN], 

(c) A write request for more than (PIPE_BUF) bytes shall either: | 

Z 111 ° ne 1)6 written - tran sfer what it can | 

260 “sly ^ten toT Mes written. When all data previ- 

*» least" (^B UF) bytes. 1 ^ h**” ^ “ 9haU transfer at j 

ass [21 V ^n no data can be written, transfer no data and return -1 I 

with errno set to [EAGAIN] 

257 U) accepted. N °^ BL °^ K c * ear ’ u;r,te 0 shall block until the data can be 

Z (2) f ‘ h ; °T N0NRL k 0CK fla e iB set, write () shall not block the process. If 

260 write wha a t “can anTreWm^h 101 * 1 the process ' writ *0 shall 

shall retifm'-l^nd errncf shall be setto^EAG^N] 8 ^ “ 

”• -*> — - j 

264 6.4.2.3 Returns 

268 6.4.2.4 Errors 

“ ~ '• " rt “° -i -4 

s “ GA ' NI i 1 ::"™;;™?? 11 y “ ■« °» “• d ** n '“' ■» «• .»»■ 

cess would be delayed in the write operation. 

274 tEBADF1 writifg^ argUment is not a vaJid Ale descriptor open for 
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308 

309 _ 


Table 6-1 - cmd Values for fcntl () 

310 

Constant 

Description 

311 

F.DUPFD 

Duplicate file descriptor. *- 

312 

f_getfd 

Get file descriptor flags. 

313 

F_GETLK 

Get record locking information. 

314 

F_SETFD 

Set file descriptor flags. 

315 

F_GETFL 

Get file status flags. 

316 

F_SETFL 

Set file status flags. 

317 

F_SETLK 

Set record locking information. 

318 

319 _ 

F_SETLKW 

Set record locking information; wait if blocked. 


320 

321 _ 

Table 6-2 - File Descriptor Flags Used for fcntl () 

322 

Constant 

Description 

323 

FD_CLOEXEC 

Close the file descriptor upon execution of an exec-family 

324 


function. 

326 _ 



326 

327 

Table 6-3 

- Ijype Values for Record Locking With fcntl () 

328 

Constant 

Description 

329 

FJRDLCK 

Shared or read lock. 

330 

f_unlck 

Unlock. 

331 

F_WRLCK 

Exclusive or write lock. 

332 




333 


Table 6-4 - oflag Values for open() 

334 _ 



335 

Constant 

Description 

336 

O.CREAT 

Create file if it does not exist. 

337 

0_EXCL 

Exclusive use flag. 

338 

0_NOCTTY 

Do not assign a controlling terminal. 

339 

0_TRUNC 

Truncate flag. 

340 


341 

342 

Table 6-5 

- File Status Flags Used for open () and fcntl() 

343 

Constant 

Description 

344 

0_ APPEND 

Set append mode. 

345 

0_NONBLOCK 

No delay. 

346 _ 



'i 


347 Table 6-6 - File Access Modes Used for open ( ) and fcntl ( ) 


348 _ 

349 

Constant 

Description 

350 

O RDONLY 

Open for reading only. 

351 

O RDWR 

Open for reading and writing. 

352 

O.WRONLY 

Open for writing only. 


353 


354 

3KR 

Table 6-7 - Mask for Use With File Access Modes 


356 

Constant 

Description 


357 

O.ACCMODE 

Mask for file access modes. 


368 





359 6.5.2.2 Description ,, 

360 The function fcntli) provides for control over open files. The argument fild&s is a 

361 file descriptor. * 

362 The available values for cmd are defined in the header <fcntl.h> (see 6.5.1), 

363 which shall include: 


364 

365 

366 

367 

368 

369 

370 

371 

372 

373 

374 
376 

376 

377 

378 

379 

380 


381 

382 

383 

384 


387 

388 


F_DUPFD 


F_GETFD 


F_SETFD 


F_GETFL 


Return a new file descriptor that is the lowest numbered avail- 
able (i.e., not already open) file descriptor greater than or equal 
to the third argument, arg, taken as an integer of type int. The 
new file descriptor refers to the same open file description as 
the original file descriptor and shares any locks. 

The FD_CLOEXEC flag associated with the new file descriptor is 
cleared to keep the file open across calls to the exec family of 
functions. 

Get the file descriptor flags, as defined in Table 6-2, that are 
associated with the file descriptor fildes. File descriptor flags 
are associated with a single file descriptor and do not affect 
other file descriptors that refer to the same file. 

Set the file descriptor flags, as defined in Table 6-2, that are 
associated with fildes to the third argument, arg , taken as type 
int. If the FD__CLOEXEC flag is zero, the file shall remain open 
across exec functions; otherwise, the file shall be closed upon 
successful execution of an exec function. 

Get the file status flags, as defined in Table 6-5, and file access 
modes for the open file description associated with fildes. The 
file access modes defined in Table 6-6 can be extracted from the 
return value using the mask 0_ACCMODE, which is defined in 
<f cntl . h>. File status flags and file access modes are associ- 
ated with the open file description and do not affect other file 
descriptors that refer to the same file with different open file 
descriptions. 
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389 F SETFL Set the file status flags, as defined in Table 6-5, for the open file 

391 fhfth vT a3SOciated ^ fiMs from the correspondin^bits^n 

392 tothe hl fie a r ment : ®'*V tak ? n aS tyPe iUt - Bits corres POnding 

393 1 th , e access modes (as defined in Table 6-6) and nfinl 

2 2 d6fined “ Table «> ‘^t are set in arg lZore f 

395 b [ a Z bltS , m Z 0tber than those mentioned here are changed 

by the application, the result is unspecified 8 

2 record°lcKlcing slmU^e'supixirted'for re' 6 / or record locking. Advisory 

398 files. nail De supported for regular files, and may be supported for other 

z f - getlk y bi y the ,ock pointed t0 by 

<oi (see tlowT V e inf “ 3 P ° inter to ^struct flock 

that t0 fCn ‘ l y the fl0Ck «‘mcture™f no I* k “ foZi 
<o< yyjT be “ 8 <“ a ‘ ad . «>e structure 

<06 fzr “?.* T nnchanged by this function call except for the lock 

type, which shall be set to F_UNLCK iock 

<o« F_SETLK ^; t n ^ d Claar b a fil ® 9< ;ement lock according to the lock description 

408 type struct I R ar "’ arg ’ taken as a pointer to 

488 shared^or^readf locks (F ^LCK) “ T* l ° eStabHab 

<10 (P wnr rtn “ „ (*_KDLCK) or exclusive (or write) locks, 

411 F RDLCK. F w T la8 10 re , m °™ either type of lock (F_UNLCK). 

412 U “ Z '-WRLCK, and F.UNLCK are defined by the 

413 M shall reTurn'immediately " eXC ‘ U8iVe Cann<>t be 96t ’ 
<i< F_ SETL KW ™ : ZT <Us the same as F.S f LK except that if a shared 

<16 wait unti the bl0Cke , d by other locks, the process shall 

<17 cauLt , t request can be satisfied. If a signal that is to be 

<i« Se f ™“ lved while fcntlO is waiting for a region the 

<19 hand er nf a h *" Upon return from the sigma! 

420 [bin™ anH ?h P Tl SS ’ f ° ShaU return ^ «rno seT to 

1EINTR1, and the lock operation shall not be done. 

<22 Ityndc^s^the mem bem'shovm'^in Table 6-8. h> head6r ’ de8Cribes an advi9 °ry lock. 

<24 able to sc^shme'riwkronThlulTOent of 16111 * * ^ ° ther processes sha H be 
426 any other process from setting an exch . r a P°^‘ lon of i‘- A shared lock prevents 
<26 area. A request for a shmed Uk shdl fad ° f the pr0tected 

<27 with read access. 1 “ the fi l e descriptor was not opened 

<29 ™2us2eZl°t lfp P orto e f ofThf JrotecZ 38 ^ 3 9hared lock ° r an 

<30 lock shall fail if the file descriptor wasCSned^th tnTaSsf “ eXClUSiV6 

S S’ 

<33 current position, or end of the file f 38 ^ fr ,° m the star t of the file, 

434 of consecutive bytes to be locked if l bn V ^ UG l ~ en is the numb er 

tone locked. If /Jen is negative, the result is undefined .The | 
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436 Table 6-8 - flock Structure 

436 __ 


437 

438 

Member 

Type 

Member 

Name 

Description 

439 

short 

tjype 

F_RDLCK, F_WRLCK, or F UNLCK. 

440 

short 

l_u> hence 

Flag for starting offset. 

441 

offj 

l_atart 

Relative offset in bytes. 

442 

Offj 

l_len 

Size; if 0, then until EOF. 

443 

pid_t 

l_pid 

Process ID of the process holding the lock, returned with F_GETLK. 

444 





446 l_pid field is only used with F_GETLK to return the process ID of the process hold- 

446 ing a blocking lock. After a successful F_GETLK request, the value of l_when.ce 

447 shall be SEEKJ3ET. 

448 Locks may start and extend beyond the current end of a file, but shall not start or 

449 extend before the beginning of the file. A lock shall be set to extend to the largest 

460 possible value of the file offset for that file if l Jen is set to zero. If the flock struct 

461 has Ijwhence and l_start that point to the beginning of the file, and l Jen of zero, 

462 the entire file shall be locked. 

463 There shall be at most one type of lock set for each byte in the file. Before a suc- 

464 cessful return from an F_SETLK or an F_SETLKW request when the calling pro- 

466 cess has previously existing locks on bytes in the region specified by the request, 

466 the previous lock type for each byte in the specified region shall be replaced by the 

467 new lock type. As specified above under the descriptions of shared locks and 

468 exclusive locks, an F_SETLK or an F_SETLKW request shall (respectively) fail or 

469 block when another process has existing locks on bytes in the specified region and 

460 the type of any of those locks conflicts with the type specified in the request. 

461 All locks associated with a file for a given process shall be removed when a file 

462 descriptor for that file is closed by that process or the process holding that file 

463 descriptor terminates. Locks are^ not inherited by a child process created using 

464 the fork ( ) function. 

466 A potential for deadlock occurs if a process controlling a locked region is put to 

466 sleep by attempting to lock the locked region of another process. If the system 

467 detects that sleeping until a locked region is unlocked would cause a deadlock, the 

468 fcntl() function shall fail with an [EDEADLK] error. 

469 6.5.2.3 Returns 

470 Upon successful completion, the value returned shall depend on cmd. The vari- 

471 ous return values are shown in Table 6-9. 

472 Otherwise, a value of -1 shall be returned and errno shall be set to indicate the 

473 error. 
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RequeHt 

F_DUPFD 

F_GETFD 

F_SETFD 

F_GETFL 

F_SETFL 

F_GETLK 

f_setlk 

F.SETLKW 


Table 6-9 - fcntlO Return Values 

Return Value 

A new file descriptor. 

Value of the flags defined in Table 6-2, but the return value shall not be negative. 
Value other than - 1 . 

Value of file status flogs and access modes, but the return value shall not be negative. 
Value other than - 1 . 

Value other than -1. 

Value other than -1. 

Value other than -1. 


6 . 5.2.4 Errors 

If any of the following conditions occur, the fcntlO function shall return -1 and set 
errno to the corresponding value: 

[EACCESl or [EAGAIN] 

The argument cmd is FJ3ETLK, the type of lock (Uype) is a 
shared lock (FJtDLCK) or exclusive lock (F_WRLCK), and the 
segment of a file to be locked is already exclusive-locked by 
another process; or the type is an exclusive lock and some por- 
tion of the segment of a hie to be locked is already shared- 
locked or exclusive-locked by another process. 


[EBADF] 


[EINTR] 

[EINVAL] 


[EMFILE] 


[ENOLCK] 


The fildes argument is not a valid file descriptor. 

The argument cmd is F_SETLK or F_SETLKW, the type of lock 
(Uype) is a shared lock (FJRDLCK), and fildes is not a valid file 
descriptor open for reading. 

The argument cmd is F_SETLK or F_SETLKW, the type of lock 
(Uype) is an exclusive lock (F_WRLCK), and fildes is not a valid 
file descriptor open for writing. 

The argument cmd is F_SETLKW, and the function was inter- 
rupted by a signal. 

The argument cmd is F_DUPFD, and the third argument is 
negative or greater than or equal to (OPEN_MAX). 

The argument cmd is F_GETLK, F.SETLK, or F_SETLKW and 
the data to which arg points is not valid, or fildes refers to a file 
that does not support locking. 

The argument cmd is F_DUPFD and (OPEN.MAX) file descrip- 
tors are currently in use by this process, or no file descriptors 
greater than or equal to arg are available. 

The argument cmd is FJ3ETLK or FJ3ETLKW, and satisfying 
the lock or unlock request would result in the number of locked 
regions in the system exceeding a system-imposed limit. 
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For each of the following conditions, if the condition is detected, the fcntU ) func- 
tion shall return -1 and set errno to the corresponding value: 

[EDEADLK] The argument cmd is F_SETLKW, and a deadlock condition was 
detected. 


520 6.5.2.S Cross-References 


521 close (), 6.3.1; exec, 3.1.2; openO, 6.3.1; <f cntl . h>, 6.5.1; 3.3.I.4. 


622 6.5.3 Reposition Read/Write File Offset 

623 Function: Iseek () 


524 6.5.3.1 Synopsis 


525 # include <sys/types .h> 

526 #include <uniscd.h> 

527 off t Iseek (int fildes, of£_t offset, int whence ) 


528 6.5.3.2 Description 

529 The fildes argument is an open file descriptor. The Iseek 0 function shall set the 
630 file offset for the open file description associated with fildes as follows: 

531 (1) If whence is SEEKJ3ET, the offset is set to offset bytes. 

632 (2) If whence is SEEK_CUR, the offset is set to its current value plus offset 

533 bytes. 

534 (3) If whence is SEEK_END, the offset is set to the size of the file plus offset 

636 bytes. . 

636 The symbolic constants SEEKJ3ET, SEEK_CUR, and SEEK.END are defined in the 
537 header <unistd . h>. 

638 Some devices are incapable of seeking. The value of the file offset associated with 

639 such a device is undefined. The behavior of the IseekO function on such devices is 

540 implementation defined. 

541 The Iseek () function shall allow the file offset to be set beyond the end of existing 

542 data in the file. If data is later written at this point, subsequent reads of data in 

543 the gap shall return bytes with the value zero until data is actually written into 

544 the gap. 

545 The Iseek () function shall not, by itself, extend the size of a file. 


Upon successful completion, the function shall return the resulting offset location 
as measured in bytes from the beginning of the file. Otherwise, it shall return a 
value of (( offj ) -1), shall set errno to indicate the error, and the file offset shall 
remain unchanged by this function call. 
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651 6. 5.3.4 Errors 

653 l a :rL th :/° ll0Wing C ° ndUionS «*«. ‘he fa«*0 function shall return -1 and 

663 set errno to the corresponding value: dna 

664 [EBADF] The fildes argument is not a valid file descriptor. 

665 [EINVAL] The whence argument is not a proper value, or the resulting file 

offset would be invalid. 

[ESPIPE1 The fildes argument is associated with a pipe or FIFO. 

668 6. 5.3.5 Cross-References 

z «** •*— <> 
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Section 7: Device- and Class-Specific Functions 


7.1 General Terminal Interface 

This section describes a general terminal interface that shall be provided. It shall 
be supported on any asynchronous communication ports if the implementation 
provides them. It is implementation defined whether this interface supports net- 
work connections or synchronous ports or both. The conformance document shall 
describe which device types are supported by these interfaces. Certain functions 
in this section apply only to the controlling terminal of a process; where this is the 
case, it is so noted. 

7.1.1 Interface Characteristics 

7.1. 1.1 Opening a Terminal Device File 

When a terminal file is opened, it normally causes the process to wait until a con- 
nection is established. In practice, application programs seldom open these files; 
they are opened by special programs and become the standard input, output, and 
error files of an application. 

As described in 5.3.1, opening a terminal device file with the 0_N0NBL0CK flag 
clear shall cause the process to block until the terminal device is ready and avail- 
able. The CLOCAL flag can also affect open(). See 7. 1.2.4. 

7.1. 1.2 Process Groups 

A terminal may have a foreground process group associated with it. This fore- 
ground process group plays a special role in handling signal-generating input 
characters, as discussed below in 7. 1.1.9. 

If the implementation supports job control (if LPOSIX_JOB_CONTROL) is defined; 
see 2.9), command interpreter processes supporting job control can allocate the 
terminal to different jobs, or process groups, by placing related processes in a sin- 
gle process group and associating this process group with the terminal. The fore- 
ground process group of a terminal may be set or examined by a process, assum- 
ing the permission requirements in this section are met; see 7.2.3 and 7.2.4. The 
terminal interface aids in this allocation by restricting access to the terminal by 
processes that are not in the foreground process group; see 7. 1.1.4. 

When there is no longer any process whose process ID or process group ID 
matches the process group ID of the foreground process group, the terminal shall 
have no foreground process group. It is unspecified whether the terminal has a 
foreground process group when there is no longer any process whose process 
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34 group ID matches the process group ID of the foreground process group, but there 
as is a process whose process ID matches. No actions defined by this part of 

36 ISO/IEC 9945, other than allocation of a controlling terminal as described in 

37 7-!.1.3 or a successful call to tcsetpgrp (), shall cause a process group to become 

38 the foreground process group of a terminal. 

39 7.1. 1.3 The Controlling Terminal 

40 A terminal may belong to a process as its controlling terminal. Each process of a 

41 session that has a controlling terminal has the same controlling terminal. A ter- 

42 minal may be the controlling terminal for at most one session. The controlling 

43 teminal for a session is allocated by the session leader in an implementation- 

44 defined manner. If a session leader has no controlling terminal and opens a ter- 

45 minal device file that is not already associated with a session without using the 

46 O_N0CTTY option (see 5.3.1), it is implementation defined whether the terminal 

47 becomes the controlling terminal of the session leader. If a process that is not a 

48 session leader opens a terminal file, or the O.NOCTTY option is used on openO 

49 that terminal shall not become the controlling terminal of the calling process! 

50 When a controlling terminal becomes associated with a session, its foreground 

51 process group shall be set to the process group of the session leader. 

62 The controlling terminal is inherited by a child process during a forkO function 

53 call A process relinquishes its controlling terminal when it creates a new session 

54 with the setsid 0 function; other processes remaining in the old session that had 

65 this terminal as their controlling terminal continue to have it. Upon the close of 

56 the last file descriptor in the system (whether or not it is in the current session) 

57 associated with the controlling terminal, it is unspecified whether all processes 

68 that, had that terminal as their controlling terminal cease to have any controlling 

59 terminal. Whether and how a session leader can reacquire a controlling terminal 

go after the controlling terminal has been relinquished in this fashion is unspecified. 

61 A process does not relinquish its controlling terminal simply by closing all of its 

62 file descnptors associated with the controlling terminal if other processes con- 

63 tinue to have it open. 

64 When a controlling process terminates, the controlling terminal is disassociated 

66 from the current session, allowing it to be acquired by a new session leader. Sub- 

66 sequent access to the terminal by other processes in the earlier session may be 

67 denied, with attempts to access the terminal treated as if modem disconnect had 

68 been sensed. 

69 7.1. 1.4 Terminal Access Control 

70 If a process is in the foreground process group of its controlling terminal read 

71 operations shall be allowed as described in 7.I.I.5. For those implementations 

72 that support job control, any attempts by a process in a background process group 

73 to read from its controlling terminal shall cause its process group to be sent a 

74 SIGTTIN signal unless one of the following special cases apply: If the reading pro- 

76 cess is ignoring or blocking the SIGTTIN signal, or if the process group of the read- 

76 ing process is orphaned, the read() returns -1 with errno set to [EIO] and no sig- 

77 nal is sent. The default action of the SIGTTIN signal is to stop the process to 

78 which it is sent. See 3.3. 1 . 1 . 
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79 If a process is in the foreground process group of its controlling terminal, write 

so operations shall be allowed as described in 7.1. 1.8. Attempts by a process in a 

81 background process group to write to its controlling terminal shall cause the pro- 

82 cess group to be sent a SIGTTOU signal unless one of the following special cases 

83 apply: If TOSTOP is not set, or if TOSTOP is set and the process is ignoring or 

84 blocking the SIGTTOU signal, the process is allowed to write to the terminal and 

85 the SIGTTOU signal is not sent. If TOSTOP is set, and the process group of the 

86 writing process is orphaned, and the writing process is not ignoring or blocking 

87 SIGTTOU, the writeO returns -1 with errno set to [EIO], and no signal is sent. 

88 Certain calls that set terminal parameters are treated in the same fashion as 

89 write, except that TOSTOP is ignored; th^t is, the effect is identical to that of ter- 

90 minal writes when TOSTOP is set. See 7.2'. 

, 91 7.1.1.5 Input Processing and Reading Data 

i 

92 A terminal device associated with a terminal device file may operate in full- 

93 duplex mode, so that data may arrive even while output is occurring. Each termi- 

94 nal device file has associated with it an input queue , into which incoming data is 

95 stored by the system before being read by a process. The system may impose a 

96 limit, (MAX_INPUT), on the number of bytes that may be stored in the input 

97 queue. The behavior of the system when this limit is exceeded is implementation 

98 defined. 

99 Two general kinds of input processing are available, determined by whether the 

100 terminal device file is in canonical mode or noncanonical mode. These modes are 

101 described in 7.1. 1.6 and 7.1. 1.7. Additionally, input characters are processed 

102 according to the c_iflag (see 7.1.2.2) and c_lflag (see 7.1. 2.5) fields. Such process- 

103 ing can include echoing , which in general means transmitting input characters 

104 immediately back to the terminal when they are received from the terminal. This 

105 is useful for terminals that can operate in full-duplex mode. 

106 The manner in which data is provided to a process reading from a terminal device 

107 file is dependent on whether the terjninal device file is in canonical or noncanoni- 

108 cal mode. 

109 Another dependency is whether the 0_NONBLOCK flag is set by openQ or fcntl{). 

110 If the 0_NONBLOCK flag is clear, then the read request shall be blocked until 

111 data is available or a signal has been received. If the 0_NONBLOCK flag is set, 

112 then the read request shall bo completed, without blocking, in one of three ways: 

113 (1) If there is enough data available to satisfy the entire request, the read{) 

114 shall complete successfully and return the number of bytes read. 

115 . (2) If there is not enough data available to satisfy the entire request, the 

116 readQ shall complete successfully, having read as much data as possible, 

117 and return the number of bytes it was able to read. 

ns (3) If there is no data available, the read() shall return -1 with errno set to 

119 [EAGAIN]. 

120 When data is available depends on whether the input processing mode is canoni- 

121 cal or noncanonical. The following subclauses, 7.1. 1.6 and 7.1. 1.7, describe each 

122 of these input processing modes. 
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123 7.1. 1.6 Canonical Mode Input Processing 

124 In canonical mode input processing, terminal input is processed in units of lines. 

12s A line is delimited by a newline ('\n') character, an end-of-file (EOF) character, or | 

126 an end-of-line (EOL) character. See 7. 1.1. 9 for more information on EOF and EOL. 

127 This means that a read request shall not return until an entire line has been 

128 typed or a signal has been received. Also, no matter how many byte9 are 

129 requested in the read call, at most one line shall be returned. It is not, however, 

iso necessary to reud u whole line ut once; any number of bytes, even one, may be 

131 requested in a read without losing information. 

132 If (MAX_CANON) is defined for this terminal device, it is a limit on the number of 

133 bytes in a line. The behavior of the system when this limit is exceeded is imple- 

134 mentation defined. If (MAX_CANON) is not defined, there is no such limit; 

135 see 2.8.5. 

136 Erase and kill processing occur when either of two special characters, the ERASE 

137 and KILL characters (see 7. 1.1.9), is received. This processing affects data in the 
13B input queue that has not yet been delimited by a newline (NL), EOF, or EOL char- 

139 acter. This undelimited data makes up the current line. The ERASE character 

140 deletes the last character in the current line, if there is any. The KILL character 

141 deletes all data in the current line, if there is any. The ERASE and KILL charac- 

142 ters have no effect if there is no data in the current line. The ERASE and KILL 

143 characters themselves are not placed in the input queue. 

144 7.1. 1.7 Noncanonical Mode Input Processing 

145 In noncanonical mode input processing, input bytes are not assembled into lines, 

146 and erase and kill processing does not occur. The values of the MIN and TIME 

147 members of the c_cc array are used to determine how to process the bytes 

148 received. 

149 MIN represents the minimum number of bytes that should be received when the 

150 read () function successfully returns. TIME is a timer of 0,1 second granularity 

151 that is used to time out short-term or bursty data transmissions. If MIN is 

152 greater than {MAX INPUT}, the response to the request is undefined. The four | 

153 possible values for MIN and TIME and their interactions are described below. 

154 7.1. 1.7.1 Case A: MIN > 0, TIME > 0 

165 In this case TIME serves as an interbyte timer and is activated after the first byte 

156 is received. Since it is an interbyte timer, it is reset after a byte is received. The 

157 interaction between MIN and TIME is as follows: as soon as one byte is received, 

158 the interbyte timer is started. If MIN bytes are received before the interbyte timer 

159 expires (remember that the timer is reset upon receipt of each byte), the read is 

loo satisfied. If the timer expires before MIN bytes are received, the characters 

161 received to that point are returned to the user. Note that if TIME expires, at least 

162 one byte shall be returned because the timer would not have been enabled unless 

163 a byte was received. In this case (MIN > 0, TIME > 0), the read shaft block until 

164 the MIN and TIME mechanisms are activated by the receipt of the first byte or 

165 until a signal is received. If data is in the buffer at the time of the readO, the | 

166 result shall be as if data had been received immediately after the readO- 
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167 7.1. 1.7.2 Case B: MIN > 0, TIME = 0 

168 In this case, since the value of TIME is zero, the timer plays no role and only MIN 

169 is significant. A pending read is not satisfied until MIN bytes are received (i.e., 

no the pending read shall block until MIN bytes are received) or a signal is received. 

171 A program that uses this case to read record-based terminal I/O may block 

172 indefinitely in the read operation. 

ns 7.1. 1.7.3 Case C: MIN - 0, TIME > 0 

174 In this case, since MIN - 0, TIME no longer represents an interbyte timer. It now 

175 serves as a read timer that is activated as soon as the readO function is pro- 

176 cessed. A read is satisfied as soon as a single byte is received or the read timer 

177 expires. Note that in this case if the timer expires, no bytes shall be returned. If 

178 the timer does not expire, the only way the read can be satisfied is if a byte is 

179 received. In this case, the read shall not block indefinitely waiting for a byte; if no 

iso byte is received within TIME*0,1 seconds after the read is initiated, the readO 

181 shall return a value of zero, having read no data. If data is in the buffer at the 

182 time of the readO , the timer shall be started as if data had been received immedi- 

183 ately after the readO . 

184 7.1. 1.7.4 Case D: MIN * 0, TIME = 0 

185 The minimum of either the number of bytes requested or the number of bytes 

186 currently available shall be returned without waiting for more bytes to be input. 

187 If no characters are av&lable, readO shall return a value of zero, having read no 

188 data. 

189 7.1. 1.8 Writing Data and Output Processing 

190 When a process writes one or more bytes to a terminal device file, they are pro- 

191 cessed according to the c_oflag field (see 7. 1.2.3). The implementation may pro- 

192 vide a buffering mechanism; as such, when a call to writeO completes, all of the 

193 bytes written have been scheduled for transmission to the device, but the 

194 transmission will not necessarily have completed. See also 6.4.2 for the effects of 

195 O.NONBLOCK on write ( ). 

196 7.1.1.9 Special Characters 

197 Certain characters have special functions on input or output or both. These func- 

198 tions are summarized as follows: 

199 INTR Special character on input and recognized if the ISIG flag (see 

200 7. 1.2.5) is enabled. It generates a SIGINT signal that is sent to 

201 all processes in the foreground process group for which the ter- 

202 minal is the controlling terminal. If ISIG is set, the INTR char- 

203 acter is discarded when processed. 

204 QUIT Special character on input and recognized if the ISIG flag is 

205 enabled. It generates a SIGQUIT signal that is sent to all 

206 processes in the foreground process group for which the termi- 

207 nal is the controlling terminal. If ISIG is set, the QUIT charac- 

208 ter is discarded when processed. 
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ERASE Special character on input and recognized if the ICANON flag is 

set. It erases the last character in the current line; see 7. 1.1.6. 
The ERASE character shall not erase beyond the start of a line, 
as delimited by an NL, EOF, or EOL character. If ICANON is 
set, the ERASE character is discarded when processed. 

KILL Special character on input and recognized if the ICANON flag is 

set. It deletes the entire line, as delimited by a NL, EOF, or 
EOL character. If ICANON is set, the KILL character is dis- 
carded when processed. 

EOF Special character on input and recognized if the ICANON flag is 

set. When received, all the bytes waiting to be read are 
immediately passed to the process, without waiting for a new- 
line, and the EOF is discarded. Thus, if there are no bytes wait- 
ing (that is, the EOF occurred at the beginning of a line), a byte 
count of zero shall be returned from the read(), representing an 
end-of-file indication. If ICANON is set, the EOF character is 
discarded when processed. 

NL Special character on input and recognized if the ICANON flag is 

set. It is the line delimiter ('\n'). 

EOL Special character on input and recognized if the ICANON flag is 

set. It is an additional line delimiter, like NL. 

SUSP Recognized on input if job control is supported (see 7. 1.2.6). If 

the ISIG flag is enabled, receipt of the SUSP character causes a 
SIGTSTP signal to be sent to all processes in the foreground pro- 
cess group for which the terminal is the controlling terminal, 
and the SUSP character is discarded when processed. 

STOP Special character on both input and output and recognized if 

the IXON (output control) or IXOFF (input control) flag is set. It 
can be used to temporarily suspend output. It is useful with 
CRT terminals to prevent output from disappearing before it 
can be read. If IXON is set, the STOP character is discarded 
when processed. 

START Special character on both input and output and recognized if 

the IXON (output control) or IXOFF (input control) flag is set. 
Can be used to resume output that has been suspended by a 
STOP character. If IXON is set, the START character is dis- 
carded when processed. 

CR Special character on input and recognized if the ICANON flag is 

set; it is the '\r', as denoted in the C Standard {2}. When 
ICANON and ICRNL are set and IGNCR is not set, this character 
is translated into a NL and has the same effect as a NL 
character. 

The NL and CR characters cannot be changed. It is implementation defined 
whether the START and STOP characters can be changed. The values for INTR, 
QUIT, ERASE, KILL, EOF, EOL, and SUSP (job control only), shall be changeable to 
suit individual tastes. 
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If LPOSIX.VDISABLE) is in effect for the terminal file, special character functions 
associated with changeable special control characters can be disabled individu- 
ally; see 7. 1.2.6. 

If two or more special characters have the same value, the function performed 
when that character is received is undefined. 

A special character is recognized not only by its value, but also by its context; for 
example, an implementation may define multibyte sequences that have a mean- 
ing different from the meaning of the bytes when considered individually. Imple- 
mentations may also define additional single-byte functions. These 
implementation-defined multibyte or single-byte functions are recognized only if 
the IEXTEN flag is set; otherwise, data is received without interpretation, except 
as required to recognize the special characters defined in this subclause (7. 1.1.9). 


267 7.1.1.10 Modem Disconnect 

268 If a modem disconnect is detected by the terminal interface for a controlling ter- 

269 minal, and if CLOCAL is not set in the c_cflag field for the terminal (see 7. 1.2.4), 

270 the SIGHUP signal is sent to the controlling process associated with the terminal. 

271 Unless other arrangements have been made, this causes the controlling process to 

272 terminate; see 3.2.2. Any subsequent call to the read() function shall return the 

273 value zero, indicating end of file. See 6.4.1. Thus, processes that read a terminal 

274 file and test for end-of-file can terminate appropriately after a disconnect. If the 

276 [EIOJ condition specified in 6.4. 1.4 that applies when the implementation supports 
276 , job control also exists, it is unspecified whether the EOF condition or the IEIO] is 

277 returned. Any subsequent writeQ to the terminal device returns -1, with errno 

278 set to [EIO], until the device is closed. 


7.1.1.11 Closing a Terminal Device File 

The last process to close a terminal device file shall cause any output to be sent to 
the device and any input to be discarded. Then, if HUPCL is set in the control 
modes and the communications poet supports a disconnect function, the terminal 
device shall perform a disconnect. 


284 7.1.2 Parameters That Can Be Set 


7. 1.2.1 termio8 Structure 

Routines that need to control certain terminal I/O characteristics shall do so by 
using the termios structure as defined in the header <termios.h>. The 
members of this structure include (but are not limited to) those shown in Table 7- 
1 . 

The types tcflagj and cc_t shall be defined in the header <termios.h>. They 
shall be unsigned integral types. 
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293 

294 

295 

296 

297 

298 

299 

300 

301 

302 



303 7. 1.2.2 Input Modes 

304 Values of the cjflag field, shown in Table 7-2, describe the basic terminal input 

305 control and are composed of the bitwise inclusive OR of the masks shown, which 

306 shall be bitwise distinct. The mask name symbols in this table are defined in 

307 <termios.h>. 


308 

309 


311 

312 

313 

314 

315 

316 

317 

318 

319 

320 

321 

322 


Table 7-2 - fermion c_ iflag Field 



BRKINT Signal interrupt on break. 

ICRNL Map CR to NL on input. 

IGNBRK Ignore break condition. 

IGNCR Ignore CR. 

IGNPAR Ignore characters with parity errors. 

INLCR Map NL to CR on input. 

INPCK Enable input parity check. 

ISTRIP Strip character. 

IXOFF Enable start/stop input control. 

EtON Enable start/stop output control. 

PARMRK Mark parity errors. 


I 


323 J 1 context of asynchronous serial data transmission, a break condition is 

324 defined as a sequence of zero-valued bits that continues for more than the time to 

325 send one byte. The entire sequence of zero-valued bits is interpreted as a single 

326 break condition, even if it continues for a time equivalent to more than one byte. 

327 In contexts other than asynchronous serial data transmission, the definition of a 
32R break condition is implementation defined. 

329 If IGNBRK is set, a break condition detected on input is ignored, that is, not put 

330 on the input queue and therefore not read by any process. If IGNBRK is not set 

331 and BRKINT is set, the break condition shall flush the input and output queues. 

332 If the terminal is the controlling terminal of a foreground process group the 

333 break condition shall generate a single SIGINT signal to that foreground process 

334 group. If neither IGNBRK nor BRKINT is set, a break condition is read as a single 

335 \0 , or if PARMRK is set, as '\377', '\0', '\0'. 

336 If IGNPAR is set, a byte with a framing or parity error (other than break) is 

337 ignored. 
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338 If PARMRK is set and IGNPAR is not set, a byte with a framing or parity error 

339 (other than break) is given to the application as the three-character sequence 

340 '\ 377 ', '\ 0 ', X, where '\ 377 ', '\ 0 ' is a two-character flag preceding each sequence 

341 and X is the data of the character received in error. To avoid ambiguity in this 

342 case, if ISTRIP is not set, a valid character of '\ 377 ' is given to the application as 

343 '\ 377 ', '\ 377 '. If neither PARMRK nor IGNPAR is set, a framing or parity error 

344 (other than break) is given to the application as a single character '\0'. 

345 If INPCK is set, input parity checking is enabled. If INPCK is not set, input parity 

346 checking is disabled, allowing output parity generation without input parity 

347 errors. Note that whether input parity checking is enabled or disabled is 

348 independent of whether parity detection is enabled or disabled (see 7. 1.2. 4). If 

349 parity detection is enabled, but input parity checking is disabled, the hardware to 

350 which the terminal is connected shall recognize the parity bit, but the terminal 

351 special file shall not check whether this bit is set correctly or not. 

352 If ISTRIP is set, valid input bytes are first stripped to seven bits; otherwise, all 

353 eight bits are processed. 

364 If INLCR is set, a received NL character is translated into a CR character. If 

355 IGNCR is set, a received CR character is ignored (not read). If IGNCR is not set 

356 and ICRNL is set, a received CR character is translated into a NL character. 

357 If IXON is set, starts top output control is enabled. A recei ved STOP character 

368 shall suspend output, and a received START character shall restart output. When 

359 IXON is set, START and STOP characters are not read, but merely perform flow 

360 control functions. When. IXON is not set, the START and STOP characters are 

361 read. 

362 If IXOFF is set, start/stop input control is enabled. The system shall transmit one 

363 or more STOP characters, which are intended to cause the terminal device to stop 

364 transmitting data, as needed to prevent the input queue from overflowing and | 

365 causing the undefined behavior described in 7. 1.1. 5 and shall transmit one or | 

366 more START characters, which are intended to cause the terminal device to 

367 resume transmitting data, as soon as the device can continue transmitting data 

368 without risk of overflowing the input queue. The precise conditions under which 

369 STOP and START characters are transmitted are implementation defined. 

370 The initial input control value alter open() is implementation defined. 

371 7.1.2.3 Output Modes 

372 Values of the cjflag field describe the basic terminal output control and are com- 

373 posed of the bitwise inclusive OR of the following masks, which shall be bitwise 

374 distinct: 


376 

i 

376 


Mask Name 
OPOST 


Description 

Perform output processing. 


377 The mask name symbols for the cjflag field are defined in ctermios . h>. 

378 If OPOST is set, output data is processed in an implementation-defined fashion so 

379 that lines of text are modified to appear appropriately on the terminal device; 
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3ro otherwise, characters are transmitted without change. 

381 The initial output control value after open{) is implementation defined. 

382 7. 1.2.4 Control Modes 

383 Values of the cjcflag field, shown in Table 7 - 3 , describe the basic terminal 

384 hardware control and are composed of the bitwise inclusive OR of the masks 

385 shown, which shall be bitwise distinct; not all values specified are required to be 

386 supported by the underlying hardware. The mask name symbols in this table are 

387 defined in ctermios . h>. 

388 Table 7-3 - termios cjcflag Field 


389 

390 

Mask Name 

Description 

391 

CLOCAL 

Ignore modem status lines. 

392 

CREAD 

Enable receiver. 

393 

CSIZE 

Number of bits per byte: 

394 

CS5 

5 bits 

395 

CS6 

6 bits 

396 

CS7 

7 bits 

397 

CS8 

8 bits 

398 

CSTOPB 

Send two stop bits, else one. 

399 

HUPCL 

Hang up on last close. 

400 

PARENB 

Parity enable. 

401 

PARODD 

Odd parity, else even. 


402 - = 

403 The CSIZE bits specify the byte size in bits for both transmission and reception. 

404 This size does not include the parity bit, if any. If CSTOPB is set, two stop bits are 

405 used; otherwise, one stop bit is used. For example, at 110 baud, two stop bits are 

406 normally used. 

407 If CREAD is set, the receiver is enabled; otherwise, no characters shall be 

408 received. 

409 If PARENB is set, parity generation and detection is enabled and a parity bit is 

410 added to each character. If parity is enabled, PARODD specifies odd parity if set; 

4 11 otherwise, even parity is used. 

412 If HUPCL is set, the modem control lines for the port shall be lowered when the 

413 last process with the port open closes the port or the process terminates. The 

414 modem connection shall be broken. 

415 If CLOCAL is set, a connection does not depend on the state of the modem status 

416 lines. If CLOCAL is clear, the modem status lines shall be monitored. 

417 Under normal circumstances, a call to the openQ function shall wait for the 

418 modem connection to complete. However, if the 0 _NONBLOCK flag is set (see 

419 5 . 3 . 1 ) or if CLOCAL has been set, the open() function shall return immediately 

420 without waiting for the connection. 

421 If the object for which the control modes are set is not an asynchronous serial con- 

422 nection, some of the modes may be ignored; for example, if an attempt is made to 
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set the baud rate on a network connection to a terminal on another host, the baud 
rate may or may not be set on the connection between that terminal and the 
machine to which it is directly connected. 

The initial hardware control value alter openi) is implementation defined. 


427 7.1.2.5 Local Modes 


Values of the cjflag held, shown in Table 7 - 4 , describe the control of various func- 
tions and are composed of the bitwise inclusive OR of the masks shown, which 
shall be bitwise distinct. The mask name symbols in this table are defined in 
<termios .h>. 


Table 7-4 - termios cjflag Field 


Description 


Mask Name 


Enable echo. 

Echo ERASE as an error-correcting backspace. 

Echo KILL. 

Echo'\n'. 

Canonical input (erase and kill processing). 

Enable extended (implementation-defined) functions. 
Enable signals. 

Disable flush after interrupt, quit, or suspend. 

Send SIGTTOU for background output. 


ECHO 

ECHOE 

ECHOK 

ECHONL 

ICANON 

IEXTEN 

ISIG 

NOFLSH 

TOSTOP 


445 If ECHO is set, input characters are echoed back to the terminal. If ECHO is not 

446 set, input characters are not echoed. 

447 If ECHOE and ICANON are set, the ERASE character shall cause the terminal to 

448 erase the last character in the current line from the display, if possible. If there is 

449 no character to erase, an implementation may echo an indication that this was 

460 the case or do nothing. 

461 If ECHOK and ICANON are set, the KILL character shall either cause the terminal 

462 to erase the line from the display or shall echo the '\n character after the KILL 

463 character. 

464 If ECHONL and ICANON are set, the '\n' character shall be echoed even if ECHO 
466 is not set. 

466 If ICANON is set, canonical processing is enabled. This enables the erase and kill 

467 edit functions and the assembly of input characters into lines delimited by NL, 

468 EOF, and EOL, as described in 7 . 1 . 1 . 6 . 

469 If ICANON is not set, read requests are satisfied directly from the input queue. A 

460 read shall not be satisfied until at least MIN bytes have been received or the 

461 timeout, value TIME has expired between bytes. The time value represents tenths 

462 of seconds. See 7 . 1 . 1.7 for more details. 

463 If ISIG is set, each input character is checked against the special control charac- 

464 ters INTR, QUIT, and SUSP (job control only). If an input character matches one of 
466 these control characters, the function associated with that character is performed. 
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466 IflSIG is not set, no checking is done. Thus, these special input functions are pos- 

467 sible only if ISIG is set. 

468 If IEXTEN is set, implementation-defined functions shall be recognized from the 

469 input data. It is implementation defined how IEXTEN being set interacts with 

470 ICANON, ISIG, IXON, or IXOFF. If IEXTEN i9 not set, then implementation-defined 

471 functions shall not be recognized, and the corresponding input characters shall be 

472 processed as described for ICANON, ISIG, IXON, and IXOFF. 

473 If NOFLSH is set, the normal flush of the input and output queues associated with 

474 the INTR, QUIT, and SUSP (job control only) characters shall not be done. 

476 If TOSTOP is set and the implementation supports job control, the signal SIGTTOU 

476 is sent to the process group of a process that tries to write to its controlling termi- 

477 nal if it is not in the foreground process group for that terminal. This signal, by 

478 default, stops the members of the process group. Otherwise, the output generated 

479 by that process is output to the current output stream. Processes that are block- 

480 ing or ignoring SIGTTOU signals are excepted and allowed to produce output, and 

481 the SIGTTOU signal is not sent. 

482 The initial local control value after open( ) is implementation defined. 

483 7. 1.2.6 Special Control Characters 

484 The special control characters values are defined by the array c_cc. The subscript 

486 name and description for each element in both canonical and noncanonical modes 

486 are shown in Table 7-5. The subscript name symbols in this table are defined in 

487 <termios.h>. 

488 Table 7-5 - termios c_cc Special Control Characters 

489 ' 

490 Subscript Usage 


491 

Canonical 

Noncanonical 

Description 

492 

Mode 

Mode 

493 

VEOF 


EOF character 

494 

VEOL 


EOL character 

495 

VERASE 


ERASE character 

496 

VINTR 

VINTR 

INTR character 

497 

VKILL 


KILL character 

498 


VMIN 

MIN value 

499 

vquit 

VQUIT 

QUIT character 

600 

VSUSP 

VSUSP 

SUSP character 

601 


VTIME 

TIME value 

602 

VSTART 

VSTART 

START character 

603 

VSTOP 

VSTOP 

STOP character 


60' 


606 The subscript values shall be unique, except that the VMIN and VTIME subscripts 

606 may have the same values as the VEOF and VEOL subscripts, respectively. 

607 Implementations that do not support job control may ignore the SUSP character 
508 value in the c_cc array indexed by the VSUSP subscript. 
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609 The value of NCOS (the number of elements in the c_cc array) is unspecified by | 

610 this part of ISO/IEC 9945. I 

611 Implementations that do not support changing the START and STOP characters 

612 may ignore the character values in the c_cc array indexed by the VSTART and 

613 VSTOP subscripts when tcsetattr( ) is called, but shall return the value in use 

614 when tcgetattrO is called. 

616 If LPOSDL.VDISABLE) is defined for the terminal device file, and the value of one 

616 of the changeable special control characters (see 7. 1.1.9) is (_POSIX_VDISABLE), 

617 that function shall be disabled, that is, no input data shall be recognized as the 

618 disabled special character. If ICANON is not set, the value of LPOSI5(_VDISABLE} 

619 has no special meaning for the VMIN and VTIME entries of the c_cc array. 

620 The initial values of all control characters are implementation defined. 

621 7. 1.2.7 Baud Rate Values I 

622 The baud rate values specified in Table 7-6 can be set into the termios structure | 

623 by the baud rate functions in 7.1.3. I 

524 
625 
526 

627 
528 

629 

630 

631 

532 

533 
634 
636 

I 

636 7.1.3 Baud Rate Functions 

637 Functions: cfgetispeedi ), cfgetospeedO, cfsetispeed( ), cfsetospeed( ) 

638 7.1.3.1 Synopsis 

639 #include <termios.h> 

540 3peed_t cfgetospeed (const struct termios +termios_p) ; 

641 int cfsetospeed (struct termios *termios_p, speed_t speed); 

642 speed_t cfgetispeed (const struct termios * termios _p ) ; 

643 int cfsetispeed (struct termios • termios j. i, speed_t speed); 


Table 7-6 - termios Baud Rate Values 


Name 

Description 

Name 

Description 

BO 

Hang up 

B600 

600 baud 

B50 

50 baud 

B1200 

1200 baud 

B75 

75 baud 

B1800 

1800 baud 

B110 

110 baud 

B2400 

2400 baud 

B134 

134.5 baud 

B4800 

4800 baud 

B150 

150 baud 

B9600 

9600 baud 

B200 

200 baud 

B19200 

19200 baud 

B300 

300 baud 

B38400 

38400 baud 
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544 7.1.3.2 Description 

545 The following interfaces are provided for getting and setting the values of the | 

546 input and output baud rates in the termios structure. The effects on the terminal | 

647 device described below do not become effective until the tesetattri ) function is sue- | 

548 cessfully called, and not all errors are detected until tesetattri. ) is called as well. | 

549 The input and output baud rates are represented in the termios structure. The | 

550 values shown in Table 7-6 are defined. The name symbols in this table are | 

661 defined in <termios . h>. J 

652 The type speedj shall be defined in <termios.h> and shall be an unsigned | 

653 integral type. | 

654 The termios jj argument is a pointer to a termios structure. | 

655 The cfgetospeedi) function shall return the output baud rate stored in the termios \ 

556 structure to which termios _p points. j 

657 The cfgetispeedi) function shall return the input baud rate stored in the termios \ 

658 structure to which termios _p points. | 

659 The cfsetospeedi ) function shall set the output baud rate stored in the termios | 

660 structure to which termios _p points. | 

661 The cfsetispeedi) function shall set the input baud rate stored in the termios | 

662 structure to which termios _p points. j 

563 Certain values for speeds that are set in the termios structure and passed to | 

664 tesetattri) have special meanings. These are discussed under tesetattri). 

665 The cfgetispeedi ) and cfgetospeedi ) functions return exactly the value found in the | 

666 termios data structure, without interpretation. j 

567 Both cfsetispeedi) and cfsetospeedi) return a value of zero if successful and -1 to | 

668 indicate an error. It is unspecified whether these return an error if an unsup- j 

669 ported baud rate is set. 

670 7. 1.3.3 Returns 

57i See 7. 1.3.2. 

672 7. 1.3.4 Errors 

573 This part of ISO/IEC 9945 does not specify any error conditions that are required 

574 to be detected for the cfgetispeedi), cfgetospeedi), cfsetispeedi), or cfsetospeedi) 

576 functions. Some errors may be detected under conditions that are unspecified by | 

676 this part of ISO/IEC 9945. 

577 7. 1.3.5 Cross-References 

678 tesetattri ), 7.2.1. 
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7.2 General Terminal Interface Control Functions 

-.'he functions that are used to control the general terminal function are described 
in this clause. If the implementation supports job control, unless otherwise noted 
for a specific command, these functions are restricted from use by background 
processes. Attempts to perform these operations shall cause the process group to 
be sent a SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU 
signals, the process is allowed to perform the operation and the SIGTTOU signal is 
not sent. 

In all the functions, fildes is an open file descriptor. However, the functions affect 
the underlying terminal file, not just the open file description associated with the 
file descriptor. \ 

7.2.1 Get and Set State 

Functions: tegetattri), tesetattri) 

7.2.1. 1 Synopsis 

♦include <termio3.h> 

int tegetattr (int fildes, struct termio3 *termios_p) ; 

int tesetattr (int fildes, int optional jactions , 
const struct termios * termios jp) ; 

7.2.1. 2 Description 

The tegetattri) function shall get the parameters associated with the object 
referred to by fildes and store them in the termios structure referenced by 
termios _p. This function is allowed from a background process; however, the ter- 
minal attributes may be subsequently changed by a foreground process. If the 
terminal device supports different input and output baud rates, the baud rates 
stored in the termios structure returned by tegetattri ) shall reflect the actual baud 
rates, even if they are equal. If differing baud rates are not supported, the rate 
returned as the output baud rate shall be the actual baud rate. The rate returned 
as the input baud rate shall be either the number zero or the output rate (as one 
of the symbolic values). Permitting either behavior is obsolescent. 4 * 

The tesetattri) function shall set the parameters associated with the terminal 
(unless support is required from the underlying hardware that is not available) 
from the termios structure referenced by termios _p as follows: 

(1) If optional jactions is TCSANOW, the change shall occur immediately. 


4) In a future revision of this part of ISO/IEC 9945, a returned value of zero as the input baud rate 
when differing baud rates are not supported may no longer be permitted. 
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614 (2) If optional jactions is TCSADRAIN, the change shall occur after all output 

6i6 written to fildes has been transmitted. This function should be used 

616 when changing parameters that affect output. 

6 1 7 (3) If optional _actions is TCSAFLUSH, the change shall occur after all output 

618 written to the object referred to by fildes has been transmitted, and all 

6 1 9 input that has been received, but not read, shall be discarded before the 

620 change is made. 

621 The symbolic constants for the values of optional jictions are defined in 

622 <termios.h>. 

623 The zero baud rate, BO, is used to terminate the connection. If BO is specified as 

624 the output baud rate when tcsetattri) is called, the modem control lines shall no 

625 longer be asserted. Normally, this will disconnect the line. 


626 If the input baud rate is equal to the numeral zero in the termios structure when | 

627 tcsetattri ) is called, the input baud rate will be changed by tcsetattri) to the same | 

628 value as that specified by the value of the output baud rate, exactly as if the input | 

629 rate had been set to the output rate by cfsetispeedi). This usage of zero is | 

630 obsolescent. 


631 The tcsetattri) function shall return success if it was able to perform any of the | 

632 requested actions, even if some of the requested actions could not be performed. | 

633 It shall set all the attributes that the implementation does support as requested | 

634 and leave all the attributes not supported by the hardware unchanged. If no part j 

636 of the request can be honored, it shall return -1 and set errno to [EINVAL]. If the | 

636 input and output baud rates differ and are a combination that is not supported, | 

637 neither baud rate is changed. A subsequent call to tcgetattri) shall return the | 

638 actual state of the terminal device [reflecting both the changes made and not | 

639 made in the previous tcsetattri) call]. The tcsetattri) function shall not change the | 

640 values in the termios structure whether or not it actually accepts them. I 

641 The termios structure may have additional fields not defined by this part of | 

642 ISO/IEC 9945. The effect of the tcsetattri ) function is undefined if the value of the | 

643 termios structure pointed to by termios _p was not derived from the result of a call | 

644 to tcgetattri) on fildes ; a Strictly Conforming POSIX.1 Application shall modify | 

646 only fields and flags defined by this part of ISO/IEC 9945 between the call to | 

646 tcgetattri) and tcsetattri), leaving all other fields and flags unmodified. I 

647 No actions defined by this part of ISO/IEC 9945, other than a call to tcsetattri) or a | 

648 close of the last file descriptor in the system associated with this terminal device, | 

649 shall cause any of the terminal attributes defined by this part of ISO/IEC 9945 to | 

660 change. I 

651 7.2.1.3 Returns 

652 Upon successful completion, a value of zero is returned. Otherwise, a value of-1 
663 is returned and errno is set to indicate the error. 
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>664 7.2. 1.4 Errors 

666 If any of the following conditions occur, the tcgetattri) function shall return -1 

656 and set errno to the corresponding value: 

657 [EBADFJ The fildes argument is not a valid file descriptor. 

668 [ENOTTY] The file associated with fildes is not a terminal. 

659 If any of the following conditions occur, the tcsetattri) function shall return —1 and 

660 set errno to the corresponding value: 

661 [EBADF] The fildes argument is not a valid file descriptor. 

662 [EINTR] A signal interrupted the tcsetattri) function. 

663 [EINVAL] The optional jictions argument is not a proper value, or an 

664 attempt was made to change an attribute represented in the 

665 termios structure to an unsupported value. 

666 [ENOTTY] The file associated with fildes is not a terminal. 

667 7.2.1.5 Cross-References 

668 1 <termios . h>, 7.1.2. 


669 7.2.2 Line Control Functions 

670 Functions: tcsendbreaki), tcdraini), tcflushi), tcflowi) 

671 7.2.2. 1 Synopsis 

672 #include <termios.h> 

673 int tcsendbreak (int fildes, int duration); 

674 int tcdrain(int fildes); 

676 int tcf lush (int fildes, int queue jselector) ; 

676 int tcflow(int fildes, int action); 


677 7.2.2.2 Description 

678 If the terminal is using asynchronous serial data transmission, the tcsendbreaki) 

679 function shall cause transmission of a continuous stream of zero-valued bits for a 

680 specific duration. If duration is zero, it shall cause transmission of zero-valued 

681 bits for at least 0,25 seconds and not more that 0,5 seconds. If duration is not 

682 zero, it shall send zero-valued bits for an implementation-defined period of time. 

683 If the terminal is not using asynchronous serial data transmission, it is imple- 

684 mentation defined whether the tcsendbreaki) function sends data to generate a 

685 break condition (as defined by the implementation) or returns without taking any 

686 action. 

687 The tcdraini) function shall wait until all output written to the object referred to 

688 by fildes has been transmitted. 
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689 Upon successful completion, the tcflushO function shall have discarded any data | 

690 written to the object referred to by fildes but not transmitted, or data received, but j 

691 not read, depending on the value of queue _selector: 

692 (1) If queue _se lector is TCIFLUSH, it shall flush data received, but not read. 

693 (2) If queue _selector is TCOFLUSH, it shall flush data written, but not 

694 transmitted. 

696 (3) If queue _selector is TCIOFLUSH, it shall flush both data received but not 

696 read and data written but not transmitted. 

697 The tcflowO function shall suspend transmission or reception of data on the object 

698 referred to by fildes , depending on the value of action : 

699 (1) If action is TCOOFF, it shall suspend output. 

700 ( 2 ) If action is TCOON, it shall restart suspended output. 

70 1 (3) If action is TCIOFF, the system shall transmit a STOP character, which is 

™2 intended to cause the terminal device to stop transmitting data to the 

703 system. (See the description of IXOFF in 7. 1.2.2.) 

704 (4) If action is TCION, the system shall transmit a START character, which is 

706 intended to cause the terminal device to start transmitting data to the 

706 system. (See the description of IXOFF in 7.I.2.2.) 

707 The symbolic constants for the values of queue jselector and action are defined in 

708 <termios.h>. 

709 The default on the opening of a terminal file is that neither its input nor its out- 

710 put is suspended. 

711 7.2.2.3 Returns 

712 Upon successful completion, a value of zero is returned. Otherwise, a value of-1 

713 is returned and errno is set to indicate the error. 

714 7.2.2.4 Errors 

716 If any of the following conditions occur, the tcsendbreakO function shall return -1 

716 and set errno to the corresponding value: 

717 [EBADF] The fildes argument is not a valid file descriptor. 

718 [ENOTTYj The file associated with fildes is not a terminal. 

719 If any of the following conditions occur, the tcdrainO function shall return —1 and 

720 set errno to the corresponding value: 

721 [EBADF] The fildes argument is not a valid file descriptor. 

722 [EINTR] A signal interrupted the tcdraini ) function. 

723 [ENOTTY] The file associated with fildes is not a terminal. 

724 If any of the following conditions occur, the tcflush() function shall return -1 and 
726 set errno to the corresponding value: 
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[EBADF] The fildes argument is not a valid file descriptor. 

[EINVAL] The queue _selector argument is not a proper value. 

[ENOTTY] The file associated with fildes is not a terminal. 

If any of the following conditions occur, the tcflowO function shall return -1 and 
set errno to the corresponding value: 

[EBADF] The fildes argument is not a valid file descriptor. 

[EINVAL] The action argument is not a proper value. 

[ENOTTY] The file associated with fildes is not a terminal. 

7.2.2.5 Cross-References 

ctermios . h>, 7.1.2. 

7.2.3 Get Foreground Process Group ED 

Function: tcgetpgrp () 

7.2.3. 1 Synopsis 

♦include <sys/types .h> 

pid_t tcgetpgrp (int fildes); | 

7.2.3.2 Description 

If LPOSIX_JOB_CONTROL) is defined: 

(1) The tcgetpgrp () function shall return the value of the process group ID of 
the foreground process group associated with the terminal. 

(2) The tcgetpgrp 0 function is allowed from a process that is a member of a 
background process group; however, the information may be subse- 
quently changed by a process that is a member of a foreground process 
group. 

Otherwise: 

The implementation shall either support the tcgetpgrp () function as 
described above or the tcgetpgrp 0 call shall fail. 

7.2. 3.3 Returns 

Upon successful completion, tcgetpgrpO returns the process group ID of the fore- 
ground process group associated with the terminal. If there is no foreground pro- | 
cess group, tcgetpgrpO shall return a value greater than 1 that does not match | 
the process group ID of any existing process group. Otherwise, a value of -1 is | 
returned and errno is set to indicate the error. 
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768 7.2.3.4 Errors 


769 If any of the following conditions occur, the tcgetpgrpO function shall return -1 

760 and set errno to the corresponding value: 

761 [EBADF] The fildes argument is not a valid file descriptor. 

762 [ENOSYS] The tcgetpgrpO function is not supported in this implementa- 

763 tion. 


764 [ENOTTY] The calling process does not have a controlling terminal, or the 

766 file is not the controlling terminal. 


766 7.2.3.5 Cross-References 

767 setsidi ), 4.3.2; setpgidQ , 4.3.3; tcsetpgrpO , 7.2.4. 


790 

[EBADF] 

The fildes argument is not a valid file descriptor. 

791 

792 

[EINVAL] 

The value of the pgrpjd argument is not supported by the 
implementation. 

793 

794 

[ENOSYS] 

The tcsetpgrpO function is not supported in this 
implementation. 

796 

796 

797 

[ENOTTY] 

The calling process does not have a controlling terminal, or the 
file is not the controlling terminal, or the controlling terminal is 
no longer associated with the session of the calling process. 

798 

799 

800 

[EPERM] 

The value of pgrpjd is a value supported by the implementa- 
tion, but does not match the process group ID of a process in the 
same session as the calling process. 


768 7.2.4 Set Foreground Process Group ID 

769 Function: tcsetpgrpO 

770 7.2.4. 1 Synopsis 

771 finclude <sys/types .h> 

772 int tc3etpgrp (int fildes, pid_t pgrp_id) ; i 

773 7.2.4.2 Description 

774 If LPOSIK_JOB_CONTROL) is defined: 

776 If the process has a controlling terminal, the tcsetpgrpO function shall set 

776 the foreground process group ID associated with the terminal to pgrpjd. 

777 The file associated with fildes must be the controlling terminal of the cal- 

778 ling process, and the controlling terminal must be currently associated with 

779 the session of the calling process. The value of pgrpjd must match a pro- 

780 cess group ID of a process in the same session as the calling process. 

781 Otherwise: 

782 The implementation shall either support the tcsetpgrpO function as 

783 described above, or the tcsetpgrpO call shall fail. 

784 7.2.4.3 Returns 

786 Upon successful completion, tcsetpgrpO returns a value of zero. Otherwise, a 

786 value of -1 is returned and errno is set to indicate the error. 

787 7.2.4.4 Errors 

788 If any of the following conditions occur, the tcsetpgrpO function shall return -1 

789 and set errno to the corresponding value: 
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Section 8: Language-Specific Services for the C Programming 
Language 


1 8.1 Referenced C Language Routine? 

2 The functions listed below are described in the indicated sections of the 

3 C Standard (2). POSIX.l with the C Language Binding comprises these functions, 

4 the extensions to them described in this clause, and the rest of the requirements 

6 stipulated in this part of ISO/1EC 9945. The functions appended with plus signs 

6 (+) have requirements beyond those set forth in the C Standard (2). Any imple- 

7 mentation claiming conformance to POSIX.l with the C Language Binding shall 

8 comply with the requirements outlined in this clause, the requirements stipulated 

9 in the rest of this part of ISO/IEC 9945, and the requirements in the indicated sec- 


10 

tions of the C Standard {2}. 

11 

For requirements concerning conformance to this clause, see 1.3.3 and its 

12 

subclauses. 

13 

4.2 

Diagnostics 

14 


Functions: assert. 

15 

4.3 

Character Handling 

16 ' 


Functions: isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, 

17 


ispunct, isspace, isupper, isxdigit, tolower, toupper. 

18 

4.4 

Localization 

19 


Functions: setlocale+. 

20 

4.5 

Mathematics 

21 


Functions: acos, asin, atan, atan2, cos, sin, tan, cosh, sinh, tanh, exp, 

22 


frexp, ldexp, log, loglO, modf, pow, sqrt, ceil, fabs, floor, fmod. 

23 

4.6 

Non-Local Jumps 

24 


Functions: setjmp, longjmp. 

25 

4.9 

Input/Output 

26 


Functions: clearerr, fclose, feof, ferror, fflush, fgetc, fgets, fopen, fputc, 

27 


fputs, fread, freopen, fseek, ftell, fwrite, getc, getchar, gets, perror, 

28 


printf, fprintf, sprintf, putc, putchar, puts, remove, rename-*-, rewind, 

29 


scanf, fscanf, sscanf, setbuf, tmpfile, tmpnam, ungetc. 

30 

4.10 

General Utilities 

31 


Functions: abs, atof, atoi, atol, rand, srand, calloc, free, malloc, realloc, 

32 


abort-*-, exit, getenv-*-, bsearch, qsort. 

33 

' 4.11 

String Handling 

34 


Functions: strcpy, stmcpy, strcat, stmcat, strcmp, stmcmp, strchr, 

35 


strcspn, strpbrk, strrchr, strspn, strstr, strtok, strlen. 
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4.12 Date and Time 

Functions: time, asctime, ctime+, gmtime+, localtime+, mktime+, 
strftime+. 

Systems conforming to this part of ISO/IEC 9945 shall make no distinction 
between the “text streams” and the “binary streams” described in the 
C Standard (2). 

For the fseek () function, if the specified position is beyond end-of-file, the conse- 
quences described in Iseek () (see 6.5.3) shall occur. 

The EXIT_SUCCESS macro, as used by the exitO function, shall evaluate to a 
value of zero. Similarly, the EXIT_FAILURE macro shall evaluate to a nonzero 
value. 

The relationship between a time in seconds since the Epoch used as an argument 
to gmtime ( ) and the tm structure (defined in <time . h>) is that the result shall be 
as specified in the expression given in the definition of seconds since the Epoch in 
2.2.2.77, where the names in the structure and in the expression correspond. If 
the time zone uctO is in effect, this shall also be true for localtime () and 
mktime (). 

8.1.1 Extensions to Time Functions 

The contents of the environment variable named TZ (see 2.6) shall be used by the 
functions dime (), localtime (), strftime (), and mktime 0 to override the default 
time zone. The value of TZ has one of the two forms (spaces inserted for clarity): 

•.characters 


std offset dst offset , rule 

If TZ is of the first format (i.e., if the first character is a colon), the characters fol- 
lowing the colon are handled in an implementation-defined manner. 

The expanded format (for all TZs whose value does not have a colon as the first 
character) is as follows: 

stdoffset[dst\offset][ , start[/time ] , end[ /time]]] 


std and dst Indicates no less than three, nor more than (TZNAME_MAX), 
bytes that are the designation for the standard (std) or summer 
(dsl) time zone. Only std is required; if cist is missing, then sum- 
mer time does not apply in this locale. Upper- and lowercase 
letters are explicitly allowed. Any characters except a leading 
colon ( : ) or digits, the comma ( , ), the minus (-), the plus (+), and 
the null character are permitted to appear in these fields, but 
their meaning is unspecified. 
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offset Indicates the value one must add to the local time to arrive at 

Coordinated Universal Time. The offset has the form: 

hh [ : mm[:ss)l 

The minutes (mm) and seconds (ss) are optional. The hour (hh) 
shall be required and may be a single digit. The offset following 
std shall be required. If no offset follows dst, summer time is 
assumed to be one hour ahead of standard time. One or more 
digits may be used; the value is always interpreted as a decimal 
number. The hour shall be between zero and 24, and the 
minutes (and seconds)— if present— between zero and 59. Use of 
values outside these ranges causes undefined behavior. If pre- 
ceded by a the time zone shall be east of the Prime Meri- 
dian; otherwise it shall be west (which may be indicated by an 
optional preceding “+”). 

rule Indicates when to change to and back from summer time. The 

rule has the form: 

date/ time, date /time 

where the first date describes when the change from standard to 
summer time occurs and the second date describes when the 
change back happens. Each time field describes when, in 
current local time, the change to the other time is made. 

The format of date shall be one of the following: 

j n The Julian day n (1 £ n < 365). Leap days shall not be 
counted. That is, in all years— including leap years— 
February 28 is day 59 and March 1 is day 60. It is 
impossible to explicitly refer to the occasional 
February 29. 

n The zero-based Julian day (0 < n 5 365). Leap days 
shall be counted, and it is possible to refer to 
February 29. 

Mm .n.d 

The d th day (0 < d £ 6) of week n of month m of the 
year (1 £ n £ 5, 1 £ m £ 12, where week 5 means “the 
last d day in month m” which may occur in either the 
fourth or the fifth week). Week 1 is the first week in 
which the rf’th day occurs. Day zero is Sunday. 

The time has the same format as offset except that no leading 
sign (“— ” or “+”) shall be allowed. The default, if time is not 
given, shall be 02:00: 00. 

Whenever dime (), strflimeO, mktime (), or localtime 0 is called, the time zone 
names contained in the external variable tzname shall be set as if the tzset 0 func- 
tion had been called. 

Applications are explicitly allowed to change TZ and have the changed TZ apply 
to themselves. 
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118 8.1.2 Extensions to setlocaleO Function 

119 Function: setlocaleO 

120 8.1.2.1 Synopsis 

121 #include <locale.h> 

122 char ♦setlocale (int category, const char * locale ) ; 

123 8.1.2.2 Description 

124 The setlocaleO function sets, changes, or queries the locale of the process accord- 

125 ing to the values of the category and the locale arguments. The possible values for 

126 category include: 

127 LC.CTYPE 

128 LC.COLLATE 

129 LCLTIME 

130 LC.NUMERIC 

131 LC_MON ET ARY 

132 Implementation-defined additional categories 

133 For POSIX.l systems, environment variables are defined that correspond to the 

134 named categories above and that have the same spelling. 

135 The value LC_ALL for category names all of the categories of the locale of the pro- 

136 cess; LC_ALL is a special constant, not a category. There is an environment vari- 

137 able LC_ALL with the semantics noted below. 

138 The locale argument is a pointer to a character string that can be an explicit 

139 string, a NULL pointer, or a null string. 

140 When locale is an explicit string, the contents of the string are implementation 

141 defined except for the value "C". The value "C" for locale specifies the minimal 

142 environment for C-language translation. If setlocaleO is not invoked, the "C" 

143 locale shall be the locale of the process. The locale name "posix" shall be recog- 

144 nized. It shall provide the same semantics as the C locale for those functions 

146 defined within this part of ISO/IEC 9945 or by the C Standard {2}. Extensions or 

146 refinements to the POSIX locale beyond those provided by the C locale may be 

147 included in future revisions, and other parts of ISO/IEC 9945 are expected to add 

148 to the requirements of the POSIX locale. 

149 When locale is a NULL pointer the locale of the process is queried according to the 
iso value of category. The content of the string returned is unspecified. 

161 When locale is a null string, the setlocaleO function takes the name of the new 

162 locale for the specified category from the environment as determined by the first 

163 condition met below: 

(1) If LC_ALL is defined in the environment and is not null, the value of 
LC_ALL is used. 

(2) If there is a variable defined in the environment with the same name as 
the category and that is not null, the value specified by that environment 
variable is used. 
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159 (3) If LANG is defined in the environment and is not null, the value of LANG 

160 is used. 

161 If the resulting value is a supported locale, setlocaleO sets the specified category 

162 of the locale of the process to that value and returns the value specified below. If 

163 the value does not name a supported locale (and is not null), setlocaleO returns a 

164 NULL pointer, and the locale of the process is not changed by this function call. If 

166 no nonnull environment variable is present to supply a value, it is implementa- 

166 tion defined whether setlocaleO sets the specified category of the locale of the pro- 

167 cess to a systemwide default value or to "C" or to "posix". The possible actual 

168 values of the environment variables are implementation defined and should 

169 appear in the system documentation. 

no Setting all of the categories of the locale of the process is similar to successively 
171 setting each individual category of the locale of the process, except that all error 

• 172 checking is done before any actions are performed. To set all the categories of the 

173 locale of the process, setlocalei ) is invoked as: 

'174 setlocale (LC_all, 

176 In this case, setlocaleO first verifies that the values of all the environment vari- 

176 ables it needs according to the precedence above indicate supported locales. If the 

177 value of any of these environment-variable searches yields a locale that is not sup- 

178 ported (and nonnull), the setlocaleO function returns a NULL pointer and the 

179 locale of the process is not changed. If all environment variables name supported 

180 locales, setlocaleO then proceeds as if it had been called for each category, using 

181 the appropriate value from the associated environment variable or from the 

182 implementation-defined default if there is no such value. 

183 8.1.2.3 Returns 

184 A successful call to setlocaleO returns a string, that corresponds to the locale set. 

186 The string returned is such that “a subsequent call with that string and its associ- 

186 ated category will restore that part of the process’s locale” (C Standard (2)). The 

187 string returned shall not be modified by the process, but may be overwritten by a 

188 subsequent call to the setlocaleO function. This string is not required to be the 

189 value of the environment variable used, if one wa9 used. 


190 8.2 C Language Input/Output Functions 

191 This clause describes input/output functions of the C Standard {2} and their 

192 interactions with other functions defined by this part of ISO/IEC 9945. 

193 All functions specified in the C Standard (2) as operating on a file name shall 

194 operate on a pathname . All functions specified in the C Standard {2} as creating a 
196 file shall do so as if they called the creatO function with a value appropriate to the 

196 C language function for the path argument and a value of 

197 S_I RUSR I S_I WUSR | S_I RGRP | S_I WGRP | S_I ROTH | S_I WOTH 

198 for the mode argument. 
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199 The type FILE and the terms file position indicator and stream are those defined I 

200 by the C Standard (2). 

201 A stream is considered local to a single process. After a fork() call, each of the 

202 parent and child have distinct streams that share an open file description. 


203 8.2.1 Map a Stream Pointer to a File Descriptor 

204 Function: fileno ( ) 

206 8.2. 1.1 Synopsis 

206 #include <3tdio.h> 

207 int f ileno (FILE * stream) ; | 


208 8.2. 1.2 Description 

209 The filenoO function returns the integer file descriptor associated with the stream 

210 (see 5.3.1). 

211 The following symbolic values in the cunistd . h> header (see 2.9) define the file 

212 descriptors that shall be associated with the C language stdin, stdout, and stderr 

213 when the application is started: 


214 

216 

216 

217 


Name 

STDIN_FILENO 

STDOUT.FILENO 

STDERR_FILENO 


Description 

Standard input value, stdin . 
Standard output value, stdout. 
Standard error value, stderr. 


Value 

0 

1 

2 


218 At entry to mainO these streams shall be in the same state as if they had just I 

220 the ™*#open ( ) railed with a mode consistent with that required by | 

220 the C Standard {2} and the file descriptor described above. i 


221 8.2.1.3 Returns 

222 See 8_2.1.2. If an error occurs, a value of -I is returned and errno is set to indi- 

223 cate tne error. 


224 8.2. 1.4 Errors 

226 tohl ZLto 9 «; 45 d ,?r 8 n0t specify error condi !ions that are required 

•m ± d h6 P"“ ( 1 f unctl0n - Some errors may be detected under condi- | 

227 tions that are unspecified by this part of ISO/IEC 9945. 

228 8.2. 1.5 Cross-References 

229 open (), 5.3.1. 
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230 8.2.2 Open a Stream on a File Descriptor 

231 Function: fdopenO 

232 8.2.2.1 Synopsis 

21(3 linclude <stdio.h> 

234 file *fdopen(int fildes , const char *type) ; I 

236 8.2.2.2 Description 

236 The fdopen 0 routine associates a stream with a file descriptor. 

237 ■ The type argument is a character string having one of the following values: 

238 "r" Open for reading. 

239 "w" Open for writing. 

240 "a" Open for writing at end-of-file. 

241 "r+" Open for update (reading and writing). 

242 "w+" Open for update (reading and writing). 

243 "a+" Open for update (reading and writing) at end-of-file. 

244 The meaning of these flags is exactly as specified by the C Standard (2) for 

245 fopenO, except that "w" and "w+" do not cause truncation of the file. Additional 

246 values for the type argument may be defined by an implementation. 

247 The application shall ensure that the mode of the stream is allowed by the mode | 

248 of the open file. I 

249 The file position indicator associated with the new stream is set to the position 

260 indicated by the file offset associated with the file descriptor. The error indicator | 

261 and end-of-file indicator for the stream shall be cleared. | 

262 | 

263 8.2.2.3 Returns 

264 If successful, the fdopenO function returns a pointer to a stream. Otherwise, a 

265 NULL pointer is returned and errno is set to indicate the error. 

266 8.2.2.4 Errors 

267 This part of ISO/IEC 9945 does not specify any error conditions that are required 

258 to be detected for the fdopenO function. Some errors may be detected under con- | 

269 ditions that are unspecified by this part oflSO/IEC 9945. 1 

260 8.2.2.5 Cross-References 

261 openO, 5.3.1; fopenO [C Standard (2)]. 
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262 8.2.3 Interactions of Other FILE-Type C Functions 

263 A single open file description can be accessed both through streams and through 

264 file descriptors. Either a file descriptor or a stream will be called a handle on the 

265 open file description to which it refers; an open file description may have several 

266 handles. 

267 Handles can be created or destroyed by user action without affecting the underly- 

268 ing open file description. Some of the ways to create them include fcntlO, dup(), 

269 fdopen ( ), filenoO, and forkO (which duplicates existing ones into new processes). 

270 They can be destroyed by at least fcloseO, close (), and the exec functions (which 

271 close some file descriptors and destroy streams). 

272 A file descriptor that is never used in an operation that could affect the file offset 

273 [for example readO, writeO, or /seeA()] is not considered a handle in this discus- 

274 sion, but could give rise to one [as a consequence otfdopenO, dupO, or fork(), for 
276 example]. This exception does include the file descriptor underlying a stream, 

276 whether created with fopenO or fdopenO, as long as it is not used directly by the 

277 application to affect the file offset. [The readO and writeO functions implicitly 

278 affect the file offset; lseek( ) explicitly affects it.] 

279 The result of function calls involving any one handle (the active handle ) are 

280 defined elsewhere in this part of ISO/IEC 9945, but if two or more handles are 

28 1 used, and any one of them is a stream, their actions shall be coordinated as 

282 described below. If this is not done, the result is undefined. 

283 A handle that is a stream is considered to be closed when either an fclose () or freo- 

264 pen{) is executed on it [the result of freopenO is a new stream for this discussion, 

286 which cannot be a handle on the same open file description as its previous value] 

286 or when the process owning that stream terminates with exitO or abortQ. A file 

287 descriptor is closed by closeO, _exit(), or by one of the exec functions when 

288 FD_CLOEXEC is set on that file descriptor. 

289 For a handle to become the active handle, the actions below must be performed 

290 between the last other use of the first handle (the current active handle) and the 

291 first other use of the second handle (the future active handle). The second handle 

292 then becomes the active handle. All activity by the application affecting the file 

293 offset on the first handle shall be suspended until it again becomes the active han- 

294 die. (If a stream function has as an underlying function that affects the file offset, 

295 the stream function will be considered to affect the file offset. The underlying 

296 functions are described below.) 

297 The handles need not be in the same process for these rules to apply. Note that | 

298 after a forkO, two handles exist where one existed before. The application shall | 

299 assure that, if both handles will ever be accessed, that they will both be in a state | 

300 where the other could become the active handle first. The application shall | 

301 prepare for a forkO exactly as if it were a change of active handle. [If the only | 

302 action performed by one of the processes is one of the exec functions or jxitO {not | 

303 exitO), the handle is never accessed in that process.] 

304 (1) For the first handle, the first applicable condition below shall apply. 

306 Afler *e actions required below are taken, the handle may be closed if it 

306 is still open. 

I 
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307 (a) If it is a file descriptor, no action is required. 

308 (b) If the only further action to be performed on any handle to this open 

309 file description is to close it, no action need be taken. 

310 (c) If it is a stream that is unbuffered, no action need be taken. 

If it is a stream that is line-buffered and the last character written | 
to the stream was a newline [that is, as if a putci' \ n') was the | 
most recent operation on that stream], no action need be taken. | 

If it is a stream that is open for writing or append (but not also open 
for reading), either an fflushO shall occur or the stream shall be 
closed. x 

If the stream is open for reading and it is at the end of the file 
[feofO is true], no action need be taken. 

If the stream is open with a mode that allows reading and the 
underlying open file description refers to a device that is capable of 
seeking, either an fflushO shall occur or the stream shall be closed. 

322 (h) Otherwise, the result is undefined. 

For the second handle: if any previous active handle has called a func- 
tion that explicitly changed the file offset, except as required above for 
the first handle, the application shall perform an IseekO or an fseekO (as 
appropriate to the type of the handle) to an appropriate location. 

If the active handle ceases to be accessible before the requirements on the 
first handle above have been met, the state of the open file description 
becomes undefined. This might occur, for example, during a forkO or an 

jexitO- 

331 ( 4 ) The exec functions shall be considered to make inaccessible all streams 

332 that are open at the time they are called, independent of what streams or 

333 file descriptors may be available to the new process image. 

334 (5) Implementations shall'assure that an application, even one consisting of 

336 several processes, shall yield correct results (no data is lost or duplicated 

336 when writing, all data is written in order, except as requested by seeks) 1 

337 when the rules above are followed, regardless of the sequence of handles 

338 used. If the rules above are not followed, the result is unspecified. When | 

339 these rules are followed, it is implementation defined whether, and under | 

340 what conditions, all input is seen exactly once. I 

341 (6) Each function that operates on a stream is said to have zero or more 

342 underlying functions. This means that the stream function shares cer- 

343 tain traits with the underlying functions, but does not require that there 

344 be any relation between the implementations of the stream function and 

346 its underlying functions. 

, 346 (7) Also, in the subclauses below, additional requirements on the standard | 

347 I/O routines, beyond those in the C Standard ( 2 ), are given. 



311 

(d) 

312 


313 


314 

(e) 

316 


316 


317 

(f) 

318 


319 

(g) 

320 


321 
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348 8.2.3. 1 fopen () 

349 The fopent) function shall allocate a file descriptor as openO does. | 

350 The underlying function is opent). 

361 8.2.S.2 fcloset) 

352 The , fcloset) function shall perform a closet) on the file descriptor that is associ- I 

363 a ted with the FILE stream. It shall also mark for update the stjctime and 

364 st_mtime fields of the underlying file, if the stream was writable, and if buffered 

365 data had not been written to the file yet. 

356 The underlying functions are write ( ) and closet ). 

367 

35fi 8. 2.3.3 freopen ( ) 

359 The freopent) function has the properties of both fcloset ) and fopen ( ). | 

3«o 8 .2.3.4 fflusht) 

361 The [flush ( ) function shall mark for update the st_ctime and stjntime fields of the I 
3«2 underlying file if the stream was writable and if buffered data had not been writ- 

363 ten to the file yet. 

364 The underlying functions are writet ) and Iseekt). | 

366 

366 8.2.3.5 fgetc ( ), fgets ( ), fread ( ), getc ( ), getchari ), gets ( ), scanft ), fscanft ) 

3«7 These functions may mark the stjitime field for update. The st_otime -field shall 

368 be marked for update by the first successful execution of one of these functions 

369 that returns data not supplied by a prior call to ungetc (). 

370 The underlying functions are readt) and Iseekt). 

371 S.2.3.6 fputc t), fputsi), fwrite t),putct), putchart), puts t ), printft ), I 

372 fprint f() | 

373 The st_ctime and stjntime fields of the file shall be marked for update between 

374 the successful execution of one of these functions and the next successful comple- 

376 tion of a call to either fflusht) or fcloset) on the same stream or a call to exiti) or 

376 abort {). 

377 The underlying functions ore writet ) and Iseekt). 

378 U /writet) writes greater than zero bytes, but fewer than requested, the error indi- I 

379 cator for ■the stream shall be set. If the underlying writet) reports an error, ernio | 

380 shall not be modified by /writet), and the error indicator for the stream shall be | 
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388 file. 

389 The underlying functions are lseek{ ) and writeO- 


390 If the most recent operation, other than ftellO, on a given stream is fflushO, the 

391 file offset in the underlying open file description shall be adjusted to reflect the 

392 location specified by the fseek(). 

393 8.2.3.8 perrori) 

394 The perror () function shall mark the file associated with the standard error | 

395 stream as having been written ( st_ctime , stjntime marked for update) at some 

396 time between its successful completion and exitO, abortO, or the completion of 

397 f flush ( ) or fclosei ) on stderr . 

398 8.2.3.9 tmpfile () 

399 The tmpfileO function shall allocate a file descriptor as fopenO does. | 

400 8.2.3.10 ftellO 

401 The underlying function is IseekO- The result of ftellO after an fflushO shall be 1 

402 the same as the result before the fflushO . If the stream is opened in append mode | 

403 or if the 0_APPEND flag is set as a consequence of dealing with other handles on | 

404 the file, the result of ftell( ) on that stream is unspecified. | 

406 8.2.3.11 Error Reporting 

406 If any of the functions above return an error indication, the value of errno shall be | 

407 set to indicate the error condition. If that error condition is one that this part of | 

408 ISO/IEC 9945 specifies to be detected by one of the corresponding underlying func- | 

409 tions, the value of errno shall be the same as the value specified for the underly- | 

410 ing function. \ 

411 8.2.3.12 exitO, abortO 

412 The exit ( ) function shall have the effect of fcloseO on every open stream, with the 

413 properties of fcloseO as described above. The abortO function shall also have | 

414 these effects if the call to abortO causes process termination, but shall have no j 

416 effect on streams otherwise. The C Standard {2} specifies the conditions where | 

416 abortO does or does not cause process termination. For the purposes of that | 


417 specification, a signal that is blocked shall not be considered caught. 
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4ifi 8.2.4 Operations on Files — the remove () Function 

419 The remove () function shall have the same effect on file times as unlinki). 

420 8.3 Other C Language Functions 

421 8.3.1 Nonlocal Jumps 

422 Functions: sigsetjmpO, siglongjmpO 

423 8.3.1. 1 Synopsis 

424 # include <setjmp.h> 

425 int sigset jmp (sig jmp_buf env , int savemask) ; 

426 void siglong jmp (sig jmp_buf enu, int val) ; 

427 8.3.1.2 Description 

428 The sigsetjmpO macro shall comply with the definition of the setjmpO macro in 

429 the C Standard (2). If the value of the savemask argument is not zero, the sig- 

430 setjmpO function shall also save the current signal mask of the process (see 3.3.1) 

431 as part of the calling environment. 

432 The siglongjmpO function shall comply with the definition of the longjmpO func- 

433 tion in the C Standard {2}. If and only if the env argument was initialized by a 

434 call to the sigsetjmpO function with a nonzero savemask argument, the 

435 siglongjmpO function shall restore the saved signal mask. 

436 8.3.1.3 Cross-References 

437 sigactionO, 3.3.4; <signal .h>, 3.3.1; sigprocmask (), 3.3.5; sigsuspendO , 3.3.7. 

438 8.3.2 Set Time Zone 

439 Function: tzsetO 

440 8.3.2. 1 Synopsis 

441 # include <time.h> 

442 void tzaet (void) ; I 

443 8.3.2.2 Description 

444 The tzsetO function uses the value of the environment variable TZ to set time 

445 conversion information used by localtime (), dime (), strftimeO , and mktime (). If 

446 TZ is absent from the environment, implementation-defined default time-zone 

447 information shall be used. 
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Section 9: System Databases 

1 9.1 System Databases 

2 The routines described in this section alloW an application to access the two sys- 

3 tem databases that are described below. 

4 The group database contains the following information for each group: 

5 (1) Group name 

6 (2) Numerical group ID 

7 (3) List of all users allowed in the group 

e The user database contains the following information for each user: 

9 (1) User name 

10 (2) Numerical user ID 

n (3) Numerical group ID 

12 (4) Initial working directory 

13 (5) Initial user program 

14 If the initial user program field is null, the system default is used. 

15 If the initial working directory field is null, the interpretation of that field is 

16 implementation defined. ^ 

17 These databases may contain other fields that are unspecified by this part of 

is ISO/IEC 9945. 
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19 9.2 Database Access 

20 9.2.1 Group Database Access 

21 Functions: getgrgidO, getgrnamO 

22 9.2. 1.1 Synopsis 

23 ♦include <sys/types . h> 

24 #include <grp.h> 

25 struct group *getgrgid (gid_t gid) ; 

26 struct group *getgrnam(const char *name) ; 

27 9.2. 1.2 Description 

28 The getgrgidO and getgrnamO routines both return pointers to an object of type 

29 struct group containing an entry from the group database with a matching gid or 

30 name. This structure, which is defined in <grp . h>, includes the members shown 

31 in Table 9-1. 


Member Member 
Type Name 


Table 9-1 - group Structure 
Description 


char * gr_name The name of the group. 

gid_t gr _gid The numerical group ID. 

char ** gr_mem A null-terminated vector of pointers to the individual member names. 


ISO/IEC 9945-1: 1990 

Part 1: SYSTEM API [C LANGUAGE] IEEE Std 1003.1-1990 

9.2.2 User Database Access 

Functions: getpwuidO, getpwnamO 

9.2.2.1 Synopsis 

♦include <sys/types .h> 

♦include <pwd.h> 

struct passwd *getpwuid (uid_t uid) ; 
struct passwd *getpwnam (const chai^ *name) ; 

9.2.2.2 Description 

The getpwuidO and getpwnamO functions both return a pointer to an object of 
type struct passwd containing an entry from the user database with a matching 
uid or name. This structure, which is defined in <pwd.h>, includes the members 
shown in Table 9-2. 


Table 9-2 - passwd Structure 


Member 

Type 

Member 

Name 

Description 

char * 

pwjiame 

User name. 

uid_t 

pwjuid 

User ED number. 

gidj 

pw_gid 

Group ID number. 

char * 

pw_dir 

Initial Working Directory. 

char * 

pw_shell 

Initial User Program. 


9.2. 1.3 Returns 

A NULL pointer is returned on error or if the requested entry is not found. 

The return values may point to static data that is overwritten by each call. 

9.2. 1.4 Errors 

This part of ISO/IEC 9945 does not specify any error conditions that are required 
to be detected for the getgrgidO or getgrnamO functions. Some errors may be I 
detected under conditions that are unspecified by this part of ISO/IEC 9945. ; 

9.2. 1.5 Cross-References 

getloginO, 4 . 2 . 4 . 


72 9.2.2.3 Returns 

73 A NULL pointer is returned on error or if the requested entry is not found. 

74 The return values may point to static data that is overwritten on each call. 

75 9.2.2.4 Errors 

76 This part of ISO/IEC 9945 does not specify any error conditions that are required 

77 to be detected for the getpwuidO or getpwnamO functions. Some errors may be | 

78 detected under conditions that are unspecified by this part of ISO/IEC 9945. I 

1 79 9.2.2.5 Cross-References 

so getloginO, 4.2.4. | 
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Section 10: Data Interchange Format 


10.1 Arclii ve/interchange File Format 

A conforming system shall provide a mechanism to copy files from a medium to 
the file hierarchy and copy files from the file hierarchy to a medium using the 
interchange formats described here. This part of ISO/I EC 9945 does not define 
this mechanism. 

When this mechanism is used to copy files from the medium by a process without 
appropriate privileges, the protection information (ownership and access permis- 
sions) shall be set in the same fashion that creatO would when given the mode 
argument matching the file permissions supplied by the mode field of the 
extended tar format or the cjnode field of the extended cpio format. A process 
with appropriate privileges shall restore the ownership and the permissions 
exactly as recorded on the medium, except that the symbolic user and group IDs 
are used for the tar format, as described in 10.1.1. 

The format-creating utility is used to translate from the file system to the formats | 
defined in this clause. The format-reading utility is used to translate from the for- | 
mats defined in this clause to a file system. The interface to these utilities, | 
including their name or names, is implementation defined. I 

The headers of these formats are defined to use characters represented in | 
ISO/IEC 646 (1); however, no restrictions are placed on the contents of the files | 
themselves. The data in a file may be binary data or text represented in any for- 
mat available to the user. When-ihese formats are used to transfer text at the 
source level, all characters shall be represented in ISO/IEC 646 {1} International | 
Reference Version (IRV). I 

The media format and the frames on the media in which the data appear are | 
unspecified by this part of ISO/IEC 9945. I 

NOTE: Guidelines are given in Annex B. I 

10.1.1 Extended tar Format 

An extended tar archive tape or file contains a series of blocks. Each block is a 
fixed-size block of 512 bytes (see below). Although this format may be thought of 
as being stored on 9-track industry-standard 12,7 mm (0,5 in) magnetic tape, | 
other types of transportable media are not excluded. Each file archived is 
represented by a header block that describes the file, followed by zero or more 
blocks that give the contents of the file. At the end of the archive file are two 
blocks filled with binary zeroes, interpreted as an end-of-archive indicator. 
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35 The blocks may be grouped for physical I/O operations. Each group of n blocks 

36 (where n is set by the application utility creating the archive file) may be written 

37 with a single write( ) operation. On magnetic tape, the result of this write is a sin- 

38 gle tape record. The last group of blocks is always at the full size, so blocks after 

39 the two zero blocks contain undefined data. 

40 The header block is structured as shown in Table 10-1. All lengths and offsets are 

41 in decimal. 

42 Table 10-1 - tar Header Block 

43 . . . 


44 

Field Name 

Byte Offset 

Length (in bytes) 

45 

name 

0 

100 

46 

mode 

100 

8 

47 

uid 

108 

8 

48 

fiid 

116 

8 

49 

size 

124 

12 

50 

mtime 

136 

12 

51 

chksum 

148 

8 

52 

typeflag 

156 

1 

53 

linkname 

157 

100 

54 

magic 

257 

6 

55 

version 

263 

2 

56 

uname 

265 

32 

57 

gname 

297 

32 

58 

dev major 

329 

8 

59 

devminor 

337 

8 

60 

prefix 

345 

155 

61 





62 

63 

Symbolic constants used in 
as follows: 

the header block are defined in the header <tar .h> 

64 

65 

♦define T MAGIC 
♦define TMAGLEN 

"ustar" 

6 

/• 

ustar and a null */ 

66 

67 

♦define TVERSION 
♦ define TVERSLEN 

••00" 

2 

/* 

00 and no null ♦ / 

68 

/* Values used in typeflag 

field */ 

69 

♦ define REGTYPE 

' O' 

/* 

Regular file */ 

70 

♦define aregtype 

'\0' 

/• 

Regular file */ 

71 

♦define LNKTYPE 

' 1 ' 

/* 

Link */ 

72 

♦define SYMTYPE 

' 2 ' 

/* 

Reserved */ 

73 

♦define CHRTYPE 

'3' 

/* 

Character special */ 

74 

♦define BLKTYPE 

' 4 ' 

/* 

Block special ♦ / 

76 

♦define DIRTYPE 

'5' 

/♦ 

Directory */ 

76 

♦define FIFOTYPE 

' 6' 

/* 

FIFO special */ 

77 

♦define CONTTYPE 

'7' 

/* 

Reserved ♦/ 


78 /* Bits used in the mode field - values in octal */ 

79 #def ine TSUID 04000 /* Set UID on execution */ 

80 #define TSGID 02000 /* Set GID on execution +/ 

81 ♦define TSVTX 01 000 /* Reserved */ 

82 /* File permissions */ 


83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 
9i 

98 

99 

100 
101 
102 

103 ( 

104 

105 

106 

107 

108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 

127 

128 
129 
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♦define TUREAD 00 400 /♦ Read by owner */ 

♦define TUWRITE 00 200 /* Write by owner ♦/ 

♦define TUEXEC 00X00 /* Execute/Search by owner */ 

♦define TGREAD 00 040 /* Read by group */ 

♦define tgwrite 00 020 /* Write by group */ 

♦define TGEXEC 00010 /* Execute/Search by group */ 

♦define TOREAD 00 004 /* Read by other */ 

♦define TOWRITE 00 002 /* Write by other */ 

♦define TOEXEC 00001 /* Execute/Search by other */ 

All characters are represented in the coded character set of ISO/IEC 646 {1}. For | 
maximum portability between implementations, names should be selected from 
characters represented by the portable filename character set as 8-bit characters 
with most significant bit zero. If an implementation supports the use of charac- | 
ters outside the portable filename character set in names for files, users, and | 
groups, one or more implementation-defined encodings of these characters shall | 
be provided for interchange purposes. However, the format-reading utility shall | 
never create file names on the local system that cannot be accessed via the func- 
tions described previously in this part of ISO/IEC 9945; see 5.3.1, 5.6.2, 5.2.1, 
6.5.2, and 5.1.2. If a file name is found on the medium that would create an 
invalid file name, the implementation shall define if the data from the file is 
stored on the file hierarchy and under what name it is stored. A format-reading 
utility may choose to ignore these files as long as it produces an error indicating 
that the file is being ignored. 

Each field within the header block is contiguous; that is, there is no padding used. 
Each character on the archive medium is stored contiguously. 

The fields magic, uname , and gname are null-terminated character strings. The 
fields name, linkname, and prefix are null-terminated character strings except 
when all characters in the array contain nonnull characters including the last 
character. The version field is two bytes containing the characters "00" (zero- 
zero). The typeflag contains a single character. All other fields are leading zero- 
filled octal numbers using digits from ISO/IEC 646 {1} IRV. Each numeric field is | 
terminated by one or more space or null characters. 

The name and the prefix fields produce the pathname of the file. The hierarchical 
relationship of the file is retained by specifying the pathname as a path prefix, 
and a slash character and filename as the suffix. A new pathname is formed, if | 
prefix is not an empty string (its first character is not null), by concatenating | 
prefix (up to the first null character), a slash character, and name', otherwise, | 
name is used alone. In either case, name is terminated at the first null character. | 
If prefix is an empty string, it is simply ignored. In this manner, pathnames of at | 
most 256 characters can be supported. If a pathname does not fit in the space 
provided, the format-creating utility shall notify the user of the error, and no 
attempt shall be made by the format-creating utility to store any part of the file — 
header or data — on the medium. 

The linkname field, described below, does not use the prefix to produce a path- 
name. As such, a linkname is limited to 100 characters. If the name does not fit | 
in the space provided, the format-creating utility shall notify the user of the error, 
and the utility shall not attempt to store the link on the medium. 
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130 The mode field provides 9 bits specifying file permissions and 3 bits to specify the 

131 set UID, set GID, and TSVTX modes. Values for these bits were defined previously. 

132 When appropriate privilege is required to set one of these mode bits, and the user 

133 restoring the files from the archive does not have the appropriate privilege, the 

134 mode bits for which the user does not have appropriate privilege shall be ignored. 

136 Some of the mode bits in the archive format are not mentioned elsewhere in this 

136 part of ISO/IEC 9945 . If the implementation does not support those bits, they may 

137 be ignored. 

138 The uid and gid fields are the user and group ID of the owner and group of the 

139 file, respectively. 

140 The size field is the size of the file in bytes. If the typeflag field is set to specify a 

141 file to be of type LNKTYPE or SYMTYPE, the size field shall be specified as zero. If 

142 the typeflag field is set to specify a file of type DIRTYPE, the size field is inter- 

143 preted as described under the definition of that record type. No data blocks are 

144 stored for LNKTYPE, SYMTYPE, or DIRTYPE. If the typeflag field is set to 

145 CHRTYPE, BLKTYPE, or FIFOTYPE, the meaning of the size field is unspecified by 

146 this part of ISO/IEC 9945 , and no data blocks are stored on the medium. Addition- 

147 ally, for FIFOTYPE, the size field shall be ignored when reading. If the typeflag 

148 field is set to any other value, the number of blocks written following the header 

149 is (size+ 511 )/ 512 , ignoring any fraction in the result of the division. 

160 The mtime field is the modification time of the file at the time it was archived. It 

151 is the ISO/IEC 646 { 1 } representation of the octal value of the modification time 

152 obtained from the stat( ) function. 

153 The chksum field is the ISO/IEC 646 ( 1 } IRV representation of the octal value of 

154 the simple sum of all bytes in the header block. Each 8 -bit byte in the header is 

155 • reated as an unsigned value. These values are added to an unsigned integer, ini- 

156 tialized to zero, the precision of which shall be no less than 17 bits. When calcu- 

157 lating the checksum, the chksum field is treated as if it were all blanks. 

158 The typeflag field specifies the type of file archived. If a particular implementa- 

169 tion does not recognize the type, or the user does not have appropriate privilege to 

160 create that type, the file shall be extracted as if it were a regular file if the file 

161 type is defined to have a meaning for the size field that could cause data blocks to 

162 be written on the medium (see the previous description for size). If conversion to 

163 an ordinary file occurs, the format-reading utility shall produce an error indicat- 

164 ing that the conversion took place. All of the typeflag fields are coded in 

165 ISO/IEC 646 ( 1 ) IRV: 

166 'O' Represents a regular file. For backward compatibility, a typeflag 

167 value of binary zero (' \ 0 ' ) should be recognized as meaning a regu- 

168 lar file when extracting files from the archive. Archives written 

169 with this version of the archive file format shall create regular files 

no with a typeflag value of ISO/IEC 646 { 1 } IRV ' 0 ' . 

171 ' 1 ' Represents a file finked to another file, of any type, previously 

172 archived. Such files are identified by each file having the same dev- 

173 ice and file serial number. The linked-to name is specified in the 

174 linkname field with a null terminator if it is less than 100 bytes in 

175 length. 
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177 

178 

179 

180 
181 
182 

183 

184 

185 

186 

187 

188 

189 

190 

191 

192 

193 


• 2 f Reserved to represent a fink to another file, of any type, whose dev- | 

ice or file serial number differs. This is provided for systems that 
support finked files whose device or file serial numbers differ, and 
should be treated as a type ' 1 ' file if this extension does not exist. 

' 3' t • 4 ' Represent character special files and block special files respectively. | 
In this case the devmajor and devminor fields shall contain informa- | 
tion defining the device, the format of which is unspecified by this | 
part of ISO/IEC 9945 . Implementations may map the device | 
specifications to their own local specification or may ignore the 
entry. 

' 5 ' Specifies a directory or subdirectory. On systems where disk alloca- | 

tion is performed on a directory basis, the size field shall contain the 
maximum number of bytes (which may be rounded to the nearest 
disk block allocation unit) that the directory may hold. A size field 
of zero indicates no such limiting. Systems that do not support lim- 
iting in this manner should ignore the size field. 

' 6 ' Specifies a FIFO special file. Note that the archiving of a FIFO file | 

archives the existence of this file and not its contents. 


194 ' 7' 

195 

196 


Reserved to represent a file to which an implementation has associ- | 
ated some high performance attribute. Implementations without 
such extensions should treat this file as a regular file (type ' 0 ' ). 


197 ' A' Z' The letters A through Z are reserved for custom implementations. | 

198 All other values are reserved for specification in future revisions of 

199 this part of ISO/IEC 9945 . 

200 The magic field is the specification that this archive was output in this archive 

201 format. If this field contains TMAGIC, the uname and gname fields shall contain 

202 the ISO/IEC 646 { 1 } IRV representation of the owner and group of the file respec- | 

203 tively (truncated to fit, if necessary). When the file is restored by a privileged, 

204 protection-preserving version of the utility, the password and group files shall be 

205 scanned for these names. If found, the user and group IDs contained within these 

W files shall be used rather than the values contained within the uid and gid fields. 


207 The encoding of the header is designed to be portable across machines. 


208 10.1.1.1 Cross-References 

209 <grp.h>, 9 . 2 . 1 ; <pwd.h>, 9 . 2 . 2 ; <sys/stat . h>, 5 . 6 . 1 ; stat(), 5 . 6 . 2 ; 

210 <unistd.h>, 2 . 9 . 


2 11 10.1.2 Extended cpio Format 

212 The byte-oriented cpio archive format is a series of entries, each comprised of a 

213 header that describes the file, the name of the file, and then the contents of the 

214 file. 

215 An archive may be recorded as a series of fixed-size blocks of bytes. This blocking 

216 shall be used only to make physical I/O more efficient. The last group of blocks is 

217 always at the full size. 
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2 ifl For the byte-oriented cpio archive format, the individual entry information must 
219 be in the order indicated and described by Table 10-2. 


220 

221 _____ 

Table 10-2 - 

Byte-Oriented cpio Archive Entry 

222 


Header 


223 

Field Name 

Length (in bytes) 

Interpreted as 

224 

cjmagic 

6 

Octal number 

226 

c_dev 

6 

Octal number 

226 

c_ino 

6 

Octal number 

227 

c_mode 

6 

Octal number 

228 

cjuid 

6 

Octal number 

229 

c_gid 

6 

Octal number 

230 

cjnlink 

6 

Octal number 

231 

c_rdev 

6 

Octal number 

232 

c_mtime 

11 

Octal number 

233 

cjnamesize 

6 

Octal number 

234 

cjilesize 

11 

Octal number 

235 

236 

Field Name 

File Name 
Length 

Interpreted as 

237 

cjname 

cjiamesize 

Pathname string 

238 

239 

Field Name 

File Data 
Length 

Interpreted as 

240 

c Jiledata 

cjilesize 

Data 


241 


242 10.1.2.1 cpio Header 

243 For each file in the archive, a header as defined previously shall be written. The 

244 information in the header fields shall be written as streams of ISO/IEC 646 (1) | 

246 characters interpreted as octal numbers. The octal numbers are extended to the | 

246 necessary length by appending ISO/IEC 646 (1) IRV zeros at the most-significant- j 

247 digit end of the number; the result is written to the stream of bytes most- 

248 significant-digit first. The fields shall be interpreted as follows: 

249 (1) cjnagic shall identify the archive as being a transportable archive by 

260 containing the magic bytes as defined by MAGIC (070707). 

261 (2) c_dev and c_ino shall contain values that uniquely identify the file within 

262 the archive (i.e., no files shall contain the same pair of cjdev and cjno 

263 values unless they are links to the same file). The values shall be deter- 

264 mined in an unspecified manner. | 

266 (3) cjnode shall contain the file type and access permissions as defined in 

266 Table 10-3. 

267 (4) cjuid shall contain the user ID of the owner. 

268 (5) c_gid shall contain the group ID of the group. 
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301 All characters are represented in ISO/IEC 646 (1) IRV. For maximum portability 

302 between implementations, names should be selected from characters represented 

303 by the portable filename character set as 8-bit characters most significant bit zero. 

304 If an implementation supports the use of characters outside the portable filename 

305 character set in names for files, users, and groups, one or more implementation- 

306 defined encodings of these characters shall be provided for interchange purposes. 

307 However, the format-reading utility shall never create file names on the local sys- 

308 tern that cannot be accessed via the functions described previously in this part of 

309 ISO/IEC 9945; see open(), stat ( ), chdir(), fcntl( ), and opendir{). If a file name is 

310 found on the medium that would create an invalid file name, the implementation 

311 shall define if the data from the file is stored on the local file system and under 

312 what name it is stored. A format-reading utility may choose to ignore these files 

313 as long as it produces an error indicating that the file is being ignored. 

314 10.1.2.3 cpio File Data 

315 Following cjiame , there shall be cjilesize bytes of data. Interpretation of such 

316 data shall occur in a manner dependent on the file. If cjilesize is zero, no data 

317 shall be contained in c Jiledata. 

318 10.1.2.4 cpio Special Entries 

319 FIFO special files, directories, and the trailer are recorded with c Jilesize equal to 

320 zero. For other special files, cjilesize is unspecified by this part of ISO/IEC 9945. ,| 

321 The header for the next file entry in the archive shall be written directly after the 

322 last byte of the file entry preceding it. A header denoting the file name 

323 trailer! ! !” shall indicate the end of the archive; the contents of bytes in the 

324 last block of the archive following such a header are undefined. 


325 10.1.2.5 cpio Values 

326 Values needed by the cpio archive format are described in Table 10-3. 

327 C_ISDIR, C_ISFIFO, and C_ISREG shall be supported on a system conforming to 

328 this part of ISO/IEC 9945; additional values defined previously are reserved for 

329 compatibility with existing systems. Additional file types may be supported; how- 

330 ever, such files should not be written on archives intended for transport to port- 

331 able systems. 

332 C_ISVTX, C_ISCTG, C_ISLNK, and C_ISSOCK have been reserved by this part of 

333 ISO/IEC 9945 to retain compatibility with some existing implementations. 

334 When restoring from an archive: 

336 If the user does not have the appropriate privilege to create a file of the 

336 specified type, the format-interpreting utility shall ignore the entry and 

337 issue an error to the standard error output. 

338 (2) Only regular files have data to be restored. Presuming a regular file 

339 meets any selection criteria that might be imposed on the format-reading 

340 utility by the user, such data shall be restored. 
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341 (3) If a user does not have appropriate privilege to set a particular mode flag, 

342 the flag shall be ignored. Some of the mode flags in the archive format 

343 are not mentioned elsewhere in this part of ISO/IEC 9945. If the imple- 

344 mentation does not support those flags, they may be ignored. 

345 10.1.2.6 Cross-References 

346 <grp.h>, 9.2.1; <pwd.h>, 9.2.2; <sys/stat . h>, 5.6.1; chmodO, 5.6.4; link (), 

347 5.3.4; mkdir(), 5.4.1; read(), 6.4.1; statO, 5.6.2. 

348 10.1.3 Multiple Volumes \ 

349 It shall be possible for data represented by the Archive/Interchange File Format 

350 to reside in more than one file. 

351 The format is considered a stream of bytes. An end-of-file (or equivalently an 

352 end-of-media) condition may occur between any two bytes of the logical byte 

353 stream. If this condition occurs, the byte following the end-of-file will be the first 

354 byte on the next file. The format-reading utility shall, in an implementation- 

355 defined manner, determine what file to read as the next file. 
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Bibliography 


1 This Annex contains lists of related open systems standards and suggested read- 

2 ing on historical implementations and application programming. 


3 A.1 Related Open Systems Standards 

4 A.1.1 Networking Standards 

5 (Bl) ISO 7498: 1984, Information processing systems — Open Systems Inter- 

6 connection — Basic Reference Model . 11 

7 (B2) ISO 8072: 1986, Information processing systems — Open Systems Inter- 

s connection — Transport service definition. 

9 (B3) ISO/IEC 8073: 1988, Information processing systems — Open Systems Inter- 

10 connection — Connection oriented transport protocol specification . 2) 

11 (B4) ISO 8326: 1987, Information processing systems — Open Systems Inter- 
im connection— Basic connection oriented session service definition. 

13 (B5) ISO 8327: 1987, Information, processing systems — Open Systems Inter- 
im connection — Basic connection oriented session protocol definition. 

is (B6) ISO 8348: 1987, Information processing systems — Data communications — 

16 Network service definition. 

17 (B7) ISO 8473: 1988, Information processing systems — Data communications — 

is Protocol for providing the connectionless-mode network service. 

19 (B8) ISO 8571: 1988, Information processing systems — Open Systems Inter- 

20 connection — File Transfer, Access and Management. 


21 

22 


1) ISO documents can be obtained from the ISO office, 1, rue de Varembd, Case Postale 56, CH-1211, 
Geneve 20, Switzerland/Suisse. 

2) EEC documents can be obtained from the IEC office, 3, rue de Varembd, Case Postale 131, CH- 
1211, Gentve 20, Switzerland/Suisse. 
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25 (B9) ISO 8649: 1988, Information processing systems — Open Systems Inter- 

26 connection — Service definition for the Association Control Service Element. 

27 (BIO) ISO 8650: 1988, Information processing systems — Open Systems Inter- 

26 connection — Protocol specification for the Association Control Service Ele- 

29 ment. 

ao (Bll) ISO 8802-2: 1989 [IEEE Std 802.2-1989 (ANSI)], Information processing 

31 systems — Local area networks — Part 2: Logical link control. 

32 {B12} ISO 8802-3: 1989 [IEEE Std 802.3-1988 (ANSI)], Information processing 

33 systems — Local area networks— Part 3: Carrier sense multiple access with 

34 collision detection (CSMAfCD) access method and physical layer 

35 specifications. 

36 [B13] I SO/I EC 8802-4: 1990 [IEEE Std 802.4-1990 (ANSI)], Information 

37 technology— Local area networks— Part 4: Token-passing bus access method 

38 and physical layer specifications. 

39 {B14} ISO 8802-5: . . . (IEEE 802.5-1989), Information technology — Local area 

40 networks— Part 5: Token ring access method and physical layer 

41 specifications. 

42 {B15} ISO 8822: 1988, Information processing systems — Open Systems Inter- 

43 connection — Connection oriented presentation service definition. 

44 (B16) ISO 8823: 1988, Information processing systems — Open Systems Inter- 

45 connection — Connection oriented presentation protocol specification. 

46 {B17} ISO 8831: 1989, Information processing systems — Open Systems Inter- 

47 connection — Job transfer and manipulation concepts and services. 

48 (B18) ISO 8832: 1989, Information processing systems — Open Systems Inter- 

49 connection — Specification of the basic class protocol for job transfer and 

so manipulation. 

51 (B19) CCITT Recommendation X.25, Interface between data terminal equipment 

52 (DTE) and data circuit-terminating equipment (DCT) for terminals operating 

53 in the packet mode and connected to public data networks by dedicated cir- 

54 cuit. 3) 

65 (B20) CCITT Recommendation X.212, Information processing systems — Data 

56 communication — Data link service definition for Open Systems Interconnec- 

57 tion. 


58 3) CCITT documents can be obtained from the CCITT General Secretariat, International 

59 Telecommunications Union, Sales Section, Place des Nations, CH-1211, Genfcve 20, 

60 Switzerlnnd/Suisse. 
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A.1.2 Language Standards 
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(B22) ISO 1989: 1985, Programming Languages — COBOL. 
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A.1.3 Graphics Standards 
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Graphical Kernel System (GKS) functional description. 

(B28) ISO 8632: 1987, Information processing systems— Computer graphics— 
Metafile for the storage and transfer of picture description information. 

(B29) ISO/IEC 9592: 1989 (ANSI X3.144-1988), Information processing systems— 
Computer graphics— Programmer's hierarchical interactive graphics system 
(PHIGS). 

A.1.4 Database Standards 

(B30) ISO 8907: 1987, Database Language— NDL. 

(B31) ISO 9075: 1987, Database Language— SQL. 

A.2 Other Standards 
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(B35) ISO 9127: 1988, Information processing systems— User documentation and 
cover information for consumer software packages. 
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interface (POSIX)— Part 2: Shell and utilities. 

4) ANSI documents can be obtained from the Snles Department, American National Standards 
Institute, 1430 Broadway, New York, NY 10018. 

5) To be approved and published. 
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122 (B49) McGilton, Henry and Morgan, Rachel. Introducing the UNIX System New 
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I2I V rose!" 1° ™° f SeV T nl that re present an industry specification in an area related to 

127 interesting^ 6 ° f docum<! " ts may be able to identify newer versions that raay be 

128 8) This entire edition is devoted to the UNIX system. 
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Annex B 

(informative) 

Rationale and Notes 


The Annex is being published as an informative part of POSIX.1 to assist in the | 
process of review. It contains historical information concerning the contents of 
POSIX.1 and why features were included or discarded. It also contains notes of | 
interest to application programmers on recommended programming practices, 
emphasizing the consequences of some aspects of POSIX.1 that may not be 
immediately apparent. 1 * 


B.I Scope and Normative References 
B.1.1 Scope 

This Rationale focuses primarily on additions, clarifications, and changes made to 
the UNIX system, from which POSIX.1 was derived. It is not a rationale for the | 
UNIX system as a whole, since the goal of POSIX.l’s developers was to codify exist- t 
ing practice, not design a new operating system. No attempt is made in this | 
Rationale to defend the pre-existing structure of UNIX systems. It is primarily 
deviations from existing practice, as codified in the base documents, that are 
explained or justified here. 

Material that is “outside the scope” or otherwise not addressed by this part of 
ISO/IEC 9945 is implicitly “unspecified.” It may be included in an implementa- 1 
tion, and thus the implementation does provide a specification for it. The term | 
“implementation-defined” has a specific meaning in POSIX.1 and is not a synonym | 
for “defined (or specified) by the implementation.” ! 

The Rationale discusses some UNIX system features that were not adopted into 
POSIX.1. Many of these are features that are popular in some UNIX system imple- 
mentations, so that a user of those implementations might question why they do 
not appear in POSIX.1. This Rationale should provide the appropriate answers. 


1) The material in this annex is derived in part from copyrighted draft documents developed under 
the sponsorship of UniForum, as part of an ongoing program of that association to support the 
POSIX standards program efforts. 
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28 There are choices allowed by POSIX.1 for some details of the interface 

29 specification; some of these are specifiable optional subsets of POSIX.1. See B.2.9. | 

30 Although the services POSEX.l provides have been defined in the C language, the 

31 concept of providing fundamental, standardized services should not be restricted 

32 only to programs of a particular programming language. The possibility of imple- 

33 menting interfaces in alternate programming languages inspired the term | 

34 POSIX.1 with the C Language Binding. The word Binding refers to the binding of | 

35 a conceptual set of services and a standardized C interface that establishes rules 

36 and syntax for accessing them. Future international standards are expected to | 

37 separate the C language binding from the language-independent services of | 

38 POSIX.1 and to include bindings for other programming languages. 

39 The C Standard (2} will be the basis for functional definitions of core services that | 

40 are independent of programming languages. POSIX.1 as it stands now can be 

41 thought of as a C Language Binding. Sections 1 through 7, and 9, correspond | 

42 roughly to the C language implementation of what will be defined in the program- | 

43 ming language-independent core services portion of POSIX.1; Section 8 | 

44 corresponds to the C language-specific portion. I 

45 The criteria used to choose the programming language-independent core services 

46 may be different from those expected. The core services represent services that 

47 are common to those programming languages likely to form language bindings to 

48 POSIX.1 — the greatest common denominator. They are not chosen to reflect the 

49 most important system services of an ideal operating system. For this reason, 

so some fundamental system services are not included in the language-independent , | 

si core. As an example, memory management routines would at first seem to be a | 

62 core service — they are an absolutely fundamental system service. They must, 

53 however, be included in language-specific portions of POSIX.1 because program- 

64 ming languages such as FORTRAN have traditionally not provided memory 

65 management. Categorizing memory management as a core service would impose 

56 unreasonable requirements for FORTRAN implementations. 

57 Any programming language traditionally supporting memory management should 

68 include those routines in the language-dependent portions of their bindings. 

59 Work will be done at a later time to standardize the classes of functions that must 

eo be included in the language-dependent portions of language bindings if those 

61 functions have been traditionally implemented for that language. This will 

62 ensure that certain classes of critical functions, such as memory management, 

63 will not be excluded from any applicable language binding; see B. 1.3.3. 

64 POSIX.1 is not a tutorial on the use of the specified interface, nor is this Rationale. 

65 However, the Rationale includes some references to well-regarded historical docu- 

66 mentation on the UNIX System in A. 3. 


67 B. 1.1.1 POSIX.1 and the C Standard 

68 Some C language functions and definitions were handled by POSIX.1, but most 

69 were handled by the C Standard (2}. The general guideline is that POSIX.1 | 

70 retained responsibility for operating-system specific functions, while the | 

71 C Standard {2} defined C library functions. See also B.2.7 and B.8. 
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There :ral areas in which the two standards differ philosophically: 

:ion parameter type lists. These appear in the syntax of the 
C Standard (2). In this version of POSIX.1, the parameter lists were res- 
tated in terms of these function prototypes. There were two major rea- 
sons for making this change from IEEE Std 1003.1-1988: the use of the 
C Standard 12) was rapidly becoming more widespread, and implemen- 
tors were experiencing difficulties with some of the function prototypes 
where guidance was not provided in POSIX.1. (The modifier const pro- 
vided the most difficulty.) Specific guidance and permission remains in 
POSIX.1 for translation to common-usage C. 

(2) Single vs. multiple processes. The C Standard (2) specifies a language 
that can be used on single-process operating systems and as a freestand- 
ing base for the implementation of operating systems or other stand- 
alone programs. However, the POSIX.1 interface is that of a multiprocess 
timesharing system. Thus, POSIX.1 has to take multiple processes into 
account in places where the C Standard (2) does not mention processes at 
all, such as killi). See also B.l.3.1.1. 

(3) Single vs. multiple operating system environments. The C Standard (2) 
specifies a language that may be useful on more than one operating sys- 
tem and thus has means of tailoring itself to the particular current 
environment. POSIX.1 is an operating system interface specification and 
thus by definition is only concerned with one operating system environ- 
ment, even though it has been carefully written to be broadly implement- 
able (see Broadly Implementable in the Introduction) in terms of various 
underlying operating systems. See also B.l.3.1.1. 

(4) Translation vs. execution environment. POSIX.1 is primarily concerned 
with the C Standard (2) execution environment, leaving the translation 
environment to the C Standard (2). See also B.l.3.1.1. 

(5) Hosted vs. freestanding implementations. All POSIX.1 implementations 
are hosted in the sense of the C Standard (2). See also the remarks on 
conformance in the Introduction. 

(6) Text vs. binary file modes. The C Standard |2) defines text and binary 
modes for a file. But the POSIX1 interface and historical implementa- 
tions related to it make no such distinction, and all functions defined by 
POSIX.1 treat files as if these modes were identical. (It should not be 
stated that POSIX1 files are either text or binary.) The definitions in the 
C Standard (2) were written so that this interpretation is possible. In 
particular, text mode files are not required to end with a line separator, 
which also means that they are not required to include a fine separator 
at all. 

Furthermore, there is a basic difference in approach between the Rationale 
accompanying the C Standard (2) and this Rationale Annex. The C Standard (2) 
Rationale, a separate document, addresses almost all changes as differences, from 
the Base Documents of the C Standard (2), usually either Kernighan and Ritchie 
(B46) or the 1984 /usr/group Standard (B59). This Rationale cannot do that, 
since there are many more variants of (and Base Documents for) the operating 
system interface than for the C language. The most noticeable aspect of this 
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119 difference is that the C Standard (2) Rationale identifies “QUIET CHANGES” from | 

120 the Base Documents. This Annex cannot include such markings, since a quiet | 

121 change from one historical implementation may correspond exactly to another his- 

122 torical implementation, and may be very noticeable to an application written for 

123 yet another. 

124 The following subclauses justify the inclusion or omission of various C language | 

125 functions in POSIX.l or the C Standard {2}. i 

126 B.l.1.1.1 Solely by POSIX.1 

127 These return parameters from the operating system environment: ctermidO, \ 

128 ttynameO, and isattyO- 

129 The filenoi) and fdopenO functions map between C language stream pointers and 

130 POSIX.1 file descriptors. 

131 B.l. 1.1.2 Solely by the C Standard | 

132 There are many functions that are useful with the operating system interface and 

133 are required for conformance with POSIX.l, but that are properly part of the 

134 C Language. These are listed in 8.1, which also notes which functions are defined 

135 by both POSIX.l and the C Standard (2). Certain terms defined by the C Standard | 

136 (2) are incorporated by POSIX.l in 2.7. j 

137 Some routines were considered too specialized to be included in POSIX.1. These | 

138 include bsearchO and qsort(). , | 

139 B.l. 1.1.3 By Neither POSIX.1 Nor the C Standard | 

ho Some functions were considered of marginal utility and problematical when inter- 

141 national character sets were considered: JoupperQ, JolowerO, toasciiO, and 

142 isascii(). 

143 Although mallocO and free () are in the C Standard {2} and are required by 8.1 of 

144 POSIX.l, neither brkO nor sbrk( ) occur in either standard (although they were in 

145 the 1984 / usr /group Standard {B59}), because POSIX.l is designed to provide the 

146 basic set of functions required to write a Conforming POSIX.l Application; the 

147 underlying implementation of mallocO or freeO is not an appropriate concern for 

148 POSIX.1. 

149 B.l. 1.1.4 Base by POSDC1, Additions by the C Standard | 

iso Since the C Standard {2} does not depend on POSIX.1 in any way, there are no 

151 items in this category. 

152 B.l. 1.1.5 Base by the C Standard, Additions by POSIX.l | 

153 The C Standard {2} has to define errno if only because examining that variable | 

154 offers the only way to determine when some mathematics routines fail. But 

155 POSIX 1 uses it more extensively and adds some semantics to it in 2.4, which also 

156 defines some values for it. 

157 Many numerical limits used by the C Standard {2} were incorporated by POSIX.l | 

158 in 2.8, and some new ones were added, all to be found in the header climits .h>. 
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The C Standard (2) provides signalO, a minimal functionality for interrupts. The 
POSIX.1 definition replaces this with an elaborate mechanism that deals with 
multiple processes and is reliable when signals come from outside sources. 

The time () function is used by the C Standard (2), but POSIX.1 further specifies 
the time value. 

The getenv () function is referenced in 2.6 and 3.1.2 and is also defined by the 
C Standard (2). 

The rename () function is extended to further specify its behavior when the new 
filename already exists or either argument refers to a directory. 

The setlocale 0 function and the handling of time zones were further specified to 
take advantage of the POSIX environment. 

The standard-I/O functions were specified in terms of their relationship to file 
descriptors and the relationship between multiple processes. 

B.l. 1.1.6 Related Functions by Both 

The C Standard (2) definition of compliance and the POSIX1 definition of confor- 
mance are similar, although the latter notes certain potential hardware 
limitations. 

POSIX1 defined a portable filename character set in 2.2.2 that is like the 
C Standard (2) identifier character set. However, POSIX.1 did not allow upper- 
and lowercase characters to be considered equivalent. See filename portability in 
2.3.4. 

The exitO function is defined only by the C Standard (2} because it refers to clos- 
ing streams, and that subject, as well as fclose 0 itself, is defined almost entirely 
by the C Standard (2). But POSIX.l defined _exitO, which also adds semantics to 
exitO- This allows POSIX.1 to omit references to the C Standard (2) atexitO 
function. 

POSIX1 defined killO, while tlje C Standard (2) defined raise (), which is similar 
except that it does not have a process ID argument, since the language defined by 
the C Standard (2) does not incorporate the idea of multiple processes. 

The new functions sigsetjmp 0 and siglongjmpO were added to provide similar 
functions to the C Standard (2) setjmp () and longjmp 0 that additionally save and 
restore signal state. 

B.1.2 Normative References 

There is no additional rationale provided for this subclause. 
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B.1.3 Conformance 

These conformance definitions are descended from those of conforming implemen- 
tation, conforming application, and conforming portable application of early 
drafts, but were changed to clarify 

(1) Extensions, options, and limits; 

(2) Relations among the three terms, and; 

(3) Relations between POSIX. 1 and the C Standard (2). 


200 B.1.3. 1 Implementation Conformance 

201 These definitions allow application developers to know what to depend on in an 

202 implementation. 

203 There is no definition of a strictly conforming implementation ; that would be an 

204 implementation that provides only those facilities specified by P0SIX.1 with no 

20 5 extensions whatsoever. This is because no actual operating system implementa- 

206 tion can exist without system administration and initialization facilities that are 

207 beyond the scope of P0SIX.1. 

2 oa B.1.3. 1.1 Requirements 

209 The word “support” is used, rather than “provide,” in order to allow an implemen- 

2 10 tahon that has no resident software development facilities, but that supports the 
2 i i execution of a Strictly Conforming POSIX.l Application , to be a conforming imple- 

212 mentation. See also B.l. 1.1. 

213 B.1.3. 1.2 Documentation 

214 The conforming documentation is required to use the same numbering scheme as 

215 POSIX. 1 for purposes of cross referencing. This requirement is consistent with 

216 and supplements the verification test assertions being developed by other POSIX 

217 groups. All options that an implementation chooses shall be reflected in 

218 <limits.h> and <unistd.h>. 

219 Note that the use of “may” in terms of where conformance documents record 

220 where implementations may vary implies that it is not required to describe those 

221 features identified as undefined or unspecified. 

222 Other aspects of systems must be evaluated by purchasers for suitability. Many 

223 systems incorporate buffering facilities, maintaining updated data in volatile 

224 storage and transferring such updates to nonvolatile storage asynchronously. 

225 Various exception conditions, such as a power failure or a system crash, can cause 

226 this data to be lost. The data may be associated with a file that is still open, with 

227 one that has been closed, with a directory, or with any other internal system data 

228 structures associated with permanent storage. This data can be lost, in whole or 

229 part, so that only careful inspection of file contents could determine that an 

230 update did not occur. 

23 i Also, interrelated file activities, where multiple files and/or directories are 

232 updated, or where space is allocated or released in the file system structures, can 

233 leave inconsistencies in the relationship between data in the various files and 
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directories, or in the file system itself. Such inconsistencies can break applica- 
tions that expect updates to occur in a specific sequence, so that updates in one 
place correspond with related updates in another place. 

For example, if a user creates a file, places information in the file, and then 
records this action in another file, a system or power failure at this point followed 
by restart may result in a state in which the record of the action is permanently 
recorded, but the file created (or some of its information) has been lost. The 
consequences of this to the user may be undesirable. For a user on such a system, 
the only safe action may be to require the system administrator to have a policy 
that requires, after any system or power failure, that the entire file system must 
be restored from the most recent backup copy (causing all intervening work to be 
lost). 

The characteristics of each implementation will vary in this respect and may or 
may not meet the requirements of a given application or user. Enforcement of 
such requirements is beyond the scope of P0SIX.1. It is up to the purchaser to 
determine what facilities are provided in an implementation that affect the expo- 
sure to possible data or sequence loss and also what underlying implementation 
techniques and/or facilities are provided that reduce or limit such loss or its 
consequences. 

B.l.3.1.3 Conforming Implementation Options 

Within POSIX. 1 there are some symbolic constants that, if defined, indicate that a 
certain option is enabled. Other symbolic constants exist in POSIX. 1 for other rea- 
sons. This clause helps clarify which constants are related to true “options” and 
which are related more to the behavior of differing systems. 

To accommodate historical implementations where there were distinct semantics 
in certain situations, but where one was not clearly better or worse than another, 
early drafts of POSIX. 1 permitted either of (typically) two options using “may.” At 
the request of the working group developing test assertions, this was changed to 
be specified by formal options with flags. It quickly became obvious that these 
would be treated as options that could be selected by a purchaser, when the intent 
of the developers of P0SIX.1 was to allow either behavior (or both, in some cases) 
to conform to the standard, and to constrain the application to accommodate 
either. Thus, these options were removed and the phrase “An implementation 
may either” introduced to replace the option. Where this phrase is used, it indi- 
cates that an application shall tolerate either behavior. 

It is intended that all conforming applications shall tolerate either behavior and 
that only in the most exceptional of circumstances (driven by technical need) 
should a purchaser specify only one behavior. Backwards compatibility is not con- 
sidered exceptional, as this is not consistent with the intent of POSIX. 1: to pro- 
mote the * portability of applications (and the development of portable 
applications). 

An application can tolerate these behaviors either by ignoring the differences (if 
they are irrelevant to the application) or by taking an action to assure a known 
state. It might be that that action would be redundant on some implementations. 

Validation programs, which are applications in this sense, could either report the 
actual result found or simply ignore the difference. In no case should either 
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acceptable behavior be treated as an error. This may complicate the validation 
slightly, but is more consistent with the intent of this permissible variation in 
behavior. 

In certain circumstances, the behavior may vary for a given process. For exam- 
ple, in the presence of networked file systems, whether or not dot and dot-dot are 
present in the directory may vary with the directory being searched, and the pro- 
gram would only be portable if it tolerated, but did not require, the presence of 
these entries in a directory. 

In situations like this, it is typically easier to simply ignore dot and dot-dot if they 
are found than to try to determine if they should be expected or not. 


B.l.3.2 Application Conformance 

These definitions guide users or adaptors of applications in determining on which 
implementations an application will run and how much adaptation would be 
required to make it run on others. These three definitions are modeled after 
related ones in the C Standard (2). 

POSIX. 1 occasionally uses the expressions portable application or conforming 
application. As they are used, these are synonyms for any of these three terms. 
The differences between the three classes of application conformance relate to the 
requirements for other standards, or, in the case of the Conforming POSIX. 1 Appli- 
cation Using Extensions, to implementation extensions. When one of the less 
explicit expressions is used, it should be apparent from the context of the discus- 
sion which of the more explicit names is appropriate. 

B. 1.3. 2.1 Strictly Conforming POSDC1 Application 

This definition is analogous to that of a C Standard (2) conforming program . 

The major difference between a Strictly Conforming POSIX. 1 Application and a 
C Standard (2) strictly conforming program is that the latter is not allowed to use 
features of POSIX.l that are not in the C Standard (2). 

B.l.3.2.2 Conforming POSIX.1 Application 

Examples of <National Bodies> include ANSI, BSI, and AFNOR. 

B.l.3.2. 3 Conforming POSIX.1 Application Using Extensions 

Due to possible requirements for configuration or implementation characteristics 
in excess of the specifications in 2.8 or related to the hardware (such as array size 
or file space), not every Conforming POSIX.l Application Using Extensions will 
run on every conforming implementation. 

B.l.3.3 Language-Dependent Services for the C Programming Language 

POSIX1 is, for historical reasons, both a specification of an operating system 
interface and a C binding for that specification. It is clear that these need to be 
separated into unique entities, but the urgency of getting the initial standard out, 
and the fact that C is the de facto primary language on systems similar to the 
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319 ' UNIX system, makes this a necessary and workable situation. 

320 Nevertheless, work will be done on language bindings, beyond that for C before 

321 the specification and the current binding are separated. Language bindings for 

322 languages other than C should not model themselves too closely on the C binding 

323 and in the process pick up various idiosyncrasies of C . 

324 Where functionality is duplicated in POSIX1 [e.g., open () and creaU )] there is no 
326 reason for that duplication to be carried forward into another language. On the 

326 other hand, some languages have functionality already in them that is essentia ly 

327 the same as that provided in POSIX.l. In this case, a mapping between the func- 

328 tionality in that language and the underlying functionality m POSIX.l is a better 

329 choice than mimicking the C binding. 

330 Since C has no syntax for I/O, and I/O is a large fraction of POSIX.l the paradigm 

331 of functions has been used. This may not be appropriate to another language 

332 For example, FORTRAN’S REWIND statement is a candidate to map onto a special 
' 333 case of IseekO, and its SEEK statement may completely cover for Iseekl). It this is 

334 the case, there is no reason to provide SUBROUTINES with the same functionality. 

335 In the more general case, file descriptors and FORTRAN’S logical unit numbers 

336 may have a useful mapping. FORTRAN’S ERR= option in I/O operations might 

337 replace returning -1; the whole concept of errors might be handled differently. 

338 As was done with C, it is not unreasonable for other language bindings to specify 

339 some areas that are undefined or unspecified by the underlying language stan- 

340 dard or that are permissible as extensions. This may, in fact, solve some difficult 

341 problems. 

342 Using as much as possible of the target language in the binding enhances porta- 

343 bility. If a program wishes to use some POSIX.l capabilities, and these are bound 

344 to the language statements rather than appearing as additional procedure or 

345 function calls, and the program does in fact conform to the language standard 

346 while using those functions, it will port to a larger range of systems than one that 

347 is obligated to use procedure or function calls introduced specifically for the bmd- 

348 ing to POSIX.l to do the same thing. 

349 A program that requires the POSIX.l capabilities that are not bound to the stan- 

350 dard language directly (as above) has no chance to be portable outside the POSIX.1 

351 environment. It does not matter whether the extension is syntactic or a new func- 

352 tion; it still will not port without effort. Given this, it seems unreasonable not to 

353 consider language extensions when determining how best to map the functionality 

364 of POSIX.1 into a particular language binding. For example, a new statement 

355 similar to READ, which loads the values from a call like stat 0, might be the best 

356 solution for reading the data lists returned as structures in C into a list of FOR- 

357 TRAN variables. 

358 No attempt to mimic printfO or scanfO (or the rest of the C Standard (2) func- 

359 tions) should be made; the equivalent functions in the language should be used. 

360 (Formatted READ and WRITE in FORTRAN, read/readln and wnte/wnteln 

361 in Pascal, for example.) 

362 There is an inherent special relationship between an operating system standard 

363 and a language standard. It is unlikely that standards for other kinds of features 

364 (such as graphics) will bind directly to statements in a general purpose language. 
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365 However, an operating system standard should provide the services required by a 

366 language. This is an unusual situation, and the tendency to use only new func- 

367 tions and procedures when creating a binding should be examined carefully. (A 

368 one-to-one binding in all cases is probably not possible, but bindings such as those 

369 for standard I/O in Section 8 may be possible.) I 

370 Binding directly to the language, where possible, should be encouraged both by 

371 making maximal use of the mapping between the operating system and the 

372 language that naturally exists and, where appropriate, by having the languages 

373 request changes to the operating system to facilitate such a mapping. (A future 

374 inclusion of a truncate function, specifically for the FORTRAN ENDFILE state- 

375 ment, but that is also generally useful, is a good example.) 

376 Part of the job of creating a binding is choosing names for functions that are intro- 

377 duced, and these will need to be appropriate for that language. It is possible to 

378 use other than the most restrictive form of a name, since, as discussed previously, 

379 using these functions inherently makes the application not portable to systems 

380 that are not POSIX. 1 , and if POSIX .1 conformant systems typically accept names 

381 that the lowest-common-denominator system will not, there is no reason to a 

382 priori exclude such names. (The specific example is C, where it is typically “non- 

383 UNIX” systems that limit external identifiers to six characters.) 

384 See B.1.1 for additional information about C bindings. 

385 B.l.3.3.1 Types of Conformance 

386 There is no additional rationale provided for this subclause. 

387 B.l. 3.3.2 C Standard Language-Dependent System Support 

388 The issue of “namespace pollution” needs to be understood in this context. See 

389 B.2.7.2. 

390 B.l. 3.3.3 Common-Usage C Language-Dependent System Support 

391 The issue of “namespace pollution” needs to be understood in this context. See 

392 B.2.7.2. 

393 B.l.3.4 Other C Language-Related Specifications 

394 The information concerning the use of library functions was adapted from a 

395 description in the C Standard {2}. Here is an example of how an application pro- 

396 gram can protect itself from library functions that may or may not be macros, 

397 rather than true functions: 

The atoi () function may be used in any of several ways: 

(1) By use of its associated header (possibly generating a macro expansion) 

♦include <stdlib.h> 

/* ... */ 
i = atoi (str ) ; 

(2) By use of its associated header (assuredly generating a true function call) 


399 

400 

401 

402 

403 
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♦include <stdlib.h> 
♦undef atoi 
/* ... */ 
i = atoi (str) ; 


♦include <stdlib.h> 
/* ... */ 
i - (atoi) (str); 


(3) By explicit declaration 


extern int atoi (const char *) ; 

/* ... */ 
i = atoi (str) ; 

(4) By implicit declaration 

/* ... */ 
i = atoi (str); 

(Assuming no function prototype is in scope. This is not allowed by the | 
C Standard (2) for functions with variable arguments; furthermore, | 
parameter type conversion “widening” is subject to different rules in this 
case.) 

Note that the C Standard {2} reserves names starting with for the compiler. 
Therefore, the compiler could, for example, implement an intrinsic, built-in func- 
tion _asm._builtin_atoi(), which it recognized and expanded into inline assembly 
code. Then, in <stdlib . h>, there could be the following: 

♦define atoi(X) _asm_builtin_atoi (X) 

The user’s “normal” call to atoi() would then be expanded inline, but the imple- 
mentor would also be required to provide a callable function named atoi() for use 
when the application requires it; for example, if its address is to be stored in a 
function pointer variable. 


432 B.l.3.5 Other Language-Related Specifications 

433 It is intended that “long” identifiers and multicase linkage would be supported on 

434 POSIX.1 systems for all languages, including C. This is where that condition is 
436 stated. The portion of the sentence about “if such extensions are” is included to 

436 permit languages that have an absolute maximum, or an absolute requirement of 

437 case folding, to be conformant. 

438 The requirement for longer names is included for several reasons: 

439 (1) Most systems similar to POSIX.1 are already conformant. 

440 (2) Many existing language standards restrict the length of names to accom- 

441 modate existing systems that cannot be modified to allow longer names. 

442 However, those systems are not expected to be POSIX.1 conformant, for 

443 other reasons. 
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444 (3) Many historical applications rely on such long names. 

445 (4) Future languages (such as FORTRAN 88) are likely to require it. 

446 Specific to FORTRAN 77 (B21), that standard permits long names, and this part of 

447 ISO/IEC 9945 requires that FORTRAN implementations running on POSIX.1 sup- 

448 port long names. The requirements of case distinction and length are considered 

449 orthogonal, but both are required if both are permitted by the language. Note 

450 that a language can be conformant to POSIX.1 even though a binding does not 

451 exist, because an application need not step outside the language standard to write 

452 a useful program. 

453 This requirement permits the use of reasonable-length names in a POSIX .1 bind- 

454 ing to a language such as FORTRAN. Clearly nothing prohibits a program that 

455 does conform to the FORTRAN minima to compile and run on POSIX.1. 

456 It is within the constraints of POSIX.1 to specify the behavior of the language pro- 

457 cessors and linker, consistent with the language, as it is a specification for an exe- 

458 cution environment. This is different than a package such as GKS (B27), which 

469 can reasonably be expected to be ported to a system that enforces the language 

460 minima. 

461 It might be argued that this specification is appropriate to the language binding 

462 committees for POSIX generally, rather than specifically to POSIX.1. That argu- 

463 ment misses the intent. The intent is to require that the linker and other code 

464 that handles “object code” (a concept not formally defined in POSIX.1) are able to 

465 support long names. This requirement, being one that spans all languages, 

466 belongs in the specification standard, rather than tied to any one language. Note; 

467 that it is also somewhat permissive, in that if the language is unable to deal with 

468 long names it is permitted not to require them, but it does remove the argument 

469 that “the loader might not permit long names, so [a specific] language binding 

470 should not force the issue.” 

471 A strictly conforming application for a given language could not use any exten- 

472 sions outside of POSIX.1 for that language (regardless of the underlying operating 

473 system). An application will strictly conform to POSIX.1 if it conforms to the 

474 language using additional interfaces from that language’s binding to POSIX.1. 


475 B.2 Definitions and General Requirements 

476 B.2.1 Conventions 

477 There is no additional rationale provided for this subclause. 
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B.2.2.1 T< 

The meanings specified in POSIX.1 for the words shall, should , and may are man- 
dated by ISO/IEC directives. 

In this Rationale, the words shall, should, and may are sometimes used to illus- 
trate similar usages in the standard. However, the Rationale itself does not 
specify anything regarding implementations or applications. 

conformance document: As a practical matter, the conformance document is 
effectively part of the system documentation. They are distinguished by POSIX.1 
so that they can be referred to distinctly. 

implementation defined: This definition is analogous to that of the 
C Standard {2} and, together with undefined and unspecified, provides a range of 
specification of freedom allowed to the interface implementor. 

may: The use of may has been limited as much as possible, due both to confu- 
sion stemming from its ordinary English meaning and to objections regarding the 
desirability of having as few options as possible and those as clearly specified as 
possible. 

shall: Declarative sentences are sometimes used in POSIX.1 as if they included 
the word shall, and facilities thus specified are no less required. For example, the 
two statements: 

(1) The fooi ) function shall return zero 

(2) The fooi ) function returns zero 

are meant to be exactly equivalent. It is expected that a future version of POSIX.1 
will be rewritten to use the “shall” form more consistently. 

should: In POSIX.1, the word should does not usually apply to the implementa- 
tion, but rather to the application. Thus, the important words regarding imple- 
mentations are shall , which indicates requirements, and may, which indicates 
options. 

obsolescent: The term obsolescent was preferred over deprecated to represent 
functionality that should not be used in new work. The term obsolescent is more 
intuitive and reduced the possibility of misunderstanding in the intended context. 

supported: An example of thi9 concept is the setpgidi ) function. If the imple- 
mentation does not support the optional job control feature, it nevertheless has to 
provide a function named setpgidi), even though its only ability is that of return- 
ing [ENOSYS]. 

system documentation: The system documentation should normally describe 
the whole of the implementation, including any extensions provided by the imple- 
mentation. Such documents normally contain information at least as detailed as 
the POSIX.1 specifications. Few requirements are made on the system documen- 
tation, but the term is needed to avoid a dangling pointer where the conformance 
document is permitted to point to the system documentation. 
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619 undefined: See implementation defined. 

620 unspecified: See implementation defined . 

621 The definitions for unspecified and undefined appear nearly identical at first 

622 examination, but are not. Unspecified means that a conforming program may 

623 deal with the unspecified behavior, and it should not care what the outcome is. 

624 Undefined says that a conforming program should not do it because no definition 
626 is provided for what it does (and implicitly it would care what the outcome was if 

626 it tried it). It is important to remember, however, that if the syntax permits the 

627 statement at all, it must have some outcome in a real implementation. 

528 Thus, the terms undefined and unspecified apply to the way the application 

629 should think about the feature. In terms of the implementation it is always 

630 “defined” — there is always some result, even if it is an error. The implementation 

631 is free to choose the behavior it prefers. 


632 

633 

534 

536 

536 

537 

538 

539 

540 

541 


This also implies that an implementation, or another standard, could specify or 
define the result in a useful fashion. The terms apply to POSIX. 1 specifically. 

The term implementation defined implies requirements for documentation that 
are not required for undefined (or unspecified). Where there is no need for a con- 
forming program to know the definition, the term undefined is used, even though 
implementation defined could also have been used in this context. There could be 
a fourth term, specifying “POSIX. 1 does not say what this does; it is acceptable to 
define it in an implementation, but it does not need to be documented,” and 
undefined would then be used very rarely for the few things for which any 
definition is not useful. 


542 In many places POSIX. 1 is silent about the behavior of some possible construct. 

543 For example, a variable may be defined for a specified range of values and 

544 behaviors are described for those values; nothing is said about what happens if 

645 the variable has any other value. That kind of silence can imply an error in the 

546 standard, but it may also imply that the standard was intentionally silent and 

5-»7 that any behavior is permitted. There is a natural tendency to infer that if the 

548 standard is silent, a behavior is prohibited. That is not the intent. Silence is 

549 intended to be equivalent to the term unspecified. 


550 B.2.2.2 General Terms 

551 Many of these definitions are necessarily circular, and some of the terms (such as 

552 process) are variants of basic computing science terms that are inherently hard to 

653 define. Some are defined by context in the prose topic descriptions of the general 

654 concepts in 2.3, but most appear in the alphabetical glossary format of the terms | 

555 in 2.2.2. j 

556 Some definitions must allow extension to cover terms or facilities that are not 

557 explicitly mentioned in POSIX.l. For example, the definition of file must permit 

558 interpretation to include streams, as found in the Eighth Edition (a research ver- 

559 sion of the UNIX system). The use of abstract intermediate terms (such as object 

560 in place of, or in addition to, file) has mostly been avoided in favor of careful 

561 definition of more traditional terms. 
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562 Some terms in the following list of notes do not appear in POSIX.l; these are 

563 marked prefixed with a asterisk (*). Many of them have been specifically 

664 excluded from POSIX.1 because they concern system administration, implementa- 

, 565 tion, or other issues that are not specific to the programming interface. Those are 

666 marked with a reason, such as “implementation defined.” 

667 appropriate privileges: One of the fundamental security problems with many 

668 historical UNIX systems has been that the privilege mechanism is monolithic — a 

569 user has either no privileges or all privileges. Thus, a successful “trojan horse” 

570 attack on a privileged process defeats all security provisions. Therefore, POSIX.l 

571 allows more granular privilege mechanisms to be defined. For many historical | 

572 implementations of the UNIX system, the presence of the term appropriate | 

573 privileges in POSIX.l may be understood as a synonym for super-user (UID 0). 

674 However, future systems will undoubtedly emerge where this is not the case and 

575 each discrete controllable action will have appropriate privileges associated with 

576 it. Because this mechanism is implementation defined , it must be described in | 

577 the conformance document. Although that description affects several parts of | 

578 POSIX.l where the term appropriate privilege is used, because the term implemen - | 

579 tation defined only appears here, the description of the entire mechanism and its | 

580 effects on these other sections belongs in clause 2.3 of the conformance document. | 

681 This is especially convenient for implementations with a single mechanism that | 

582 applies in all areas, since it only needs to be described once. I 

583 clock tick: The C Standard {2} defines a similar interval for use by the clockQ | 

,584 function. There is nQ requirement that these intervals be the same. In historical | 

685 implementations these intervals are different. Currently only the timesi ) function | 

586 uses values stated in terms of clock ticks, although other functions might use | 

587 them in the future. I 

588 controlling terminal: The question of which of possibly several special files 

589 referring to the terminal is meant is not addressed in POSIX.l. 

590 ' | 

591 ^device number: The conceptis handled in stat() as ID of device. 

692 directory: The format of the directory file is implementation defined and differs 

593 radically between System V and 4.3BSD. However, routines (derived from 

594 4.3BSD) for accessing directories are provided in 5.1.2 and certain constraints on 
596 the format of the information returned by those routines are made in 5.1.1. 

596 directory entry: Throughout the document, the term link is used (about the | 

697 link () function, for example] in describing the objects that point to files from | 

sue directories. 


599 dot: The symbolic name dot is carefully used in POSIX.l to distinguish the work- 

600 ing directory filename from a period or a decimal point. 


601 

602 

603 

604 

605 


dot-dot: Historical implementations permit the use of these filenames without 
their special meanings. Such use precludes any meaningful use of these 
filenames by a Conforming POSIX.1 Application. Therefore, such use is considered 
an extension, the use of which makes an implementation nonconforming. See also 
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606 Epoch: Historically, the origin of UNIX system time was referred to as “00:00:00 

607 GMT, January 1, 1970.” Greenwich Mean Time is actually not a term ack- 

6oa nowledged by the international standards community; therefore, this term, 

609 Epoch , is used to abbreviate the reference to the actual standard, Coordinated 

610 Universal Time. The concept of leap seconds is added for precision; at the time 

611 POSIX.l was published, 14 leap seconds had been added since January 1, 1970. 

612 These 14 seconds are ignored to provide an easy and compatible method of com- 

613 puting time differences. 

614 Most systems’ notion of “time” is that of a continuously increasing value, so this 

615 value should increase even during leap seconds. However, not only do most sys- 

616 terns not keep track of leap seconds, but most systems are probably not synchron- 

617 ized to any standard time reference. Therefore, it is inappropriate to require that 

618 a time represented as seconds since the Epoch precisely represent the number of 

619 seconds between the referenced time and the Epoch. 

620 It is sufficient to require that applications be allowed to treat this time as if it 

621 represented the number of seconds between the referenced time and the Epoch. It 

622 is the responsibility of the vendor of the system, and the administrator of the sys- 

623 tem, to ensure that this value represents the number of seconds between the 

624 referenced time and the Epoch as closely as necessary for the application being 

625 run on that system. 

626 It is important that the interpretation of time names and seconds since the Epoch 

627 values be consistent across conforming systems. That is, it is important that all 

628 conforming systems interpret “536457599 seconds since the Epoch” as 59 

629 seconds, 59 minutes, 23 hours 31 December 1986, regardless of the accuracy of 

630 the system’s idea of the current time. The expression is given to assure a con- 

631 sistent interpretation, not to attempt to specify the calendar. The relationship 

632 between tm_yday and the day of week, day of month, and month is presumed to 

633 be specified elsewhere and is not given in POSIX.l. 

634 Consistent interpretation of seconds since the Epoch can be critical to certain 

635 types of distributed applications that rely on such timestamps to synchronize 

636 events. The accrual of leap seconds in a time standard is not predictable. The 

637 number of leap seconds since the Epoch will likely increase. POSIX.l is more con- 

638 cemed about the synchronization of time between applications of astronomically 

639 short duration. These concerns are expected to become more critical in the future. | 

640 Note that tmjyday is zero-based, not one-based, so the day number in the exam- 

641 pie above is 364. Note also that the division is an integer division (discarding 

642 remainder) as in the C language. 

643 Note also that in Section 8, the meaning of gmtimeO, localtime (), and mktime () is | 

644 specified in terms of this expression. However, the C Standard {2} computes 

645 tm_yday from tmjnday , tm_mon, and tmjyear in mktime (). Because it is stated 

646 as a (bidirectional) relationship, not a function, and because the conversion 

647 between month-day-year and day-of-year dates is presumed well known and is 

648 also a relationship, this is not a problem. 

649 Note that the expression given will fail after the year 2099. Since the issue of 

650 timejt overflowing a 32-bit integer occurs well before that time, both of these will 

651 have to be addressed in revisions to POSIX.l. 
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652 FIFO special file: See pipe in B. 2.2.2. 

653 file: It is permissible for an implementation-defined file type to be nonreadable 

654 or non writable. 

655 file classes: These classes correspond to the historical sets of permission bits. 

656 The classes are general to allow implementations flexibility in expanding the 

657 access mechanism for more stringent security environments. Note that a process 

658 is in one and only one class, so there is no ambiguity. 

659 filename: At the present time, the primary responsibility for truncating 

660 filenames containing multibyte characters must reside with the application. | 

661 Some industry groups involved in internationalization believe that in the future | 

662 the responsibility must reside with the kernel. For the moment, a clearer under- 

663 standing of the implications of making the kernel responsible for truncation of 

664 multibyte file names is needed. 

665 Character level truncation was. not adopted because there is no support in | 
6 (i6 POSIX.1 that advises how the kernel distinguishes between single and multi byte | 

667 characters. Until that time, it must be incumbent upon application writers to 

668 determine where multibyte characters must be truncated. 

669 file system: Historically the meaning of this term has been overloaded with two 

670 meanings: that of the complete file hierarchy and that of a mountable subset of 

671 that hierarchy; i.e., a mounted file system. POSIX1 uses the term file system in 

672 the second sense, except that it is limited to the scope of a process (and a process s 

673 root directory). This usage also clarifies the domain in which a file serial number 

674 is unique. 

676 *group file: Implementation defined; see B.9. 

676 *historical implementations: This refers to previously existing implementa- 

677 tions of programming interfaces and operating systems that are related to the 

678 interface specified by POSIX1. See also “Minimal Changes to Historical Imple- | 

679 mentations” in the Introduction. I 

680 * hosted implementation: TKis refers to a POSIX1 implementation that is 

681 accomplished through interfaces from the POSIX.l services to some alternate form 

682 of operating system kernel services. Note that the line between a hosted imple- 

683 mentation and a native implementation is blurred, since most implementations 

684 will provide some services directly from the kernel and others through some 

685 indirect path. [For example, fbpenO might use openO ; or mkfifbQ might use 

686 mknodO .] There is no necessary relationship between the type of implementation 

687 and its correctness, performance, and/or reliability. 

688 *implementation: The term is generally used instead of its synonym, system, 

689 to emphasize the consequences of decisions to be made by system implementors. 

690 Perhaps if no options or extensions to POSIX.l were allowed, this usage would not 

691 have occurred. 

692 The term specific implementation is sometimes used as a synonym for implemen- 
ts tation . This should not be interpreted too narrowly; both terms can represent a 

694 relatively broad group of systems. For example, a hardware vendor could market 

695 a very wide selection of systems that all used the same instruction set, with some 

696 systems desktop models and others large multiuser minicomputers. This wide 
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697 range would probably share a common POSIX.l operating system, allowing an 

698 application compiled for one to be used on any of the others; this is a [specific] 

699 implementation . 

700 However, that wide range of machines probably has some differences between the 

701 models. Some may have different clock rates, different file systems, different 

702 resource limits, different network connections, etc., depending on their sizes or 

703 intended usages. Even on two identical machines, the system administrators may 

704 configure them differently. Each of these different systems is known by the term 

705 a specific instance of a specific implementation . This term is only used in the por- 

706 tions of POSIX.l dealing with run-time queries: sysconfO and pathconfi ). 

707 -“incomplete pathname: Absolute pathname has been adequately defined. 

708 job control: In order to understand the job-control facilities in POSIX.l it is use- 

709 ful to understand how they are used by a job-control-cognizant shell to create the 

710 user interface effect of job control. 

7 11 While the job-control facilities supplied by POSIX .1 can, in theory, support dif- 

712 ferent types of interactive job-control interfaces supplied by different types of 

713 shells, there is historically one particular interface that is most common (provided 

714 by BSD C Shell). This discussion describes that interface as a means of illustrat- 

715 ing how the POSIX.l job-control facilities can be used. 

716 Job control allows users to selectively stop (suspend) the execution of processes 

717 and continue (resume) their execution at a later point. The user typically employs 

718 this facility via the interactive interface jointly supplied by the terminal I/O driver 

719 and a command interpreter (shell). 

720 The user can launch jobs (command pipelines) in either the foreground or back- 

721 ground. When launched in the foreground, the shell waits for the job to complete 

722 before prompting for additional commands. When launched in the background, 

723 the shell does not wait, but immediately prompts for new commands. 

724 If the user launches a job in the foreground and subsequently regre.ts this, the 

725 user can type the suspend character (typically set to control-Z), which causes the 

726 foreground job to stop and the shell to begin prompting for new commands. The 

727 stopped job can be continued by the user (via special shell commands) either as a 

728 foreground job or as a background job. Background jobs can also be moved into 

729 the foreground via shell commands. 

730 If a background job attempts to access the login terminal (controlling terminal), it 

731 is stopped by the terminal driver and the shell is notified, which, in turn, notifies 

732 the user. [Terminal access includes read( ) and certain terminal control functions 

733 and conditionally includes write().] The user can continue the stopped job in the 

734 foreground, thus allowing the terminal access to succeed in an orderly fashion. 

735 After the terminal access succeeds, the user can optionally move the job into the 

736 background via the suspend character and shell commands. 

737 Implementing Job Control Shells 

738 The interactive interface described previously can be accomplished using the 

739 POSIX .1 job-control facilities in the following way. 

740 The key feature necessary to provide job control is a way to group processes into 

741 jobs. This grouping is necessary in order to direct signals to a single job and also 
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742 to identify which job is in the foreground. (There is at most one job that is in the 

743 foreground on any controlling terminal at a time.) 

744 The concept of process groups is used to provide this grouping. The shell places 

746 each job in a separate process group via the setpgidO function. To do this, the 

746 setpgidO function is invoked by the shell for each process in the job. It is actually 

747 useful to invoke setpgidO twice for each process: once in the child process, after 

748 calling forkO to create the process, but before calling one of the exec functions to 

749 begin execution of the program, and once in the parent shell process, after calling 

750 fork 0 to create the child. The redundant invocation avoids a race condition by 

751 ensuring that the child process is placed into the new process group before either 

752 the parent or the child relies on this being the case. The process group ID for the 

753 job is selected by the shell to be equal , to the process ID of one of the processes in 

764 the job. Some shells choose to make one process in the job be the parent of the 

756 other processes in the job (if any). Other shells (e.g., the C Shell) choose to make 

766 themselves the parent of all processes in the pipeline (job). In order to support 

757 this latter case, the setpgidO function accepts a process group ID parameter since 

758 the correct process group ID cannot be inherited from the shell. The shell itself is 
769 considered to be a job and is the sole process in its own process group. 

760 The shell also controls which job is currently in the foreground. A foreground and 

76 1 background job differ in two ways: the shell waits for a foreground command to 

762 complete (or stop) before continuing to read new commands, and the terminal I/O 

763 driver inhibits terminal access by background jobs (causing the processes to stop). 

764 Thus, the shell must work cooperatively with the terminal I/O driver and have a 

765 common understanding of which job is currently in the foreground. It is the user 

766 who decides which command should be currently in the foreground, and the user 

767 informs the shell via shell commands. The shell, in turn, informs the terminal I/O 

768 driver via the tcsetpgrpO function. This indicates to the terminal I/O driver the 

769 process group ID of the foreground process group (job). When the current fore- 

770 ground job either stops or terminates, the shell places itself in the foreground via 

771 tcsetpgrpO before prompting for additional commands. Note that when a job is 

772 created the new process group begins as a background process group. It requires 

773 an explicit act of the shell via tcsetpgrpO to move a process group (job) into the 

774 foreground. 

776 When a process in a job stops or terminates, its parent (e.g., the shell) receives 

776 synchronous notification by calling the waitpidO function with the WUNTRACED 

777 flag set. Asynchronous notification is also provided when the parent establishes a 

778 signal handler for SIGCHLD and does not specify the SAJNOCLDSTOP flag. Usu- 

779 ally all processes in a job stop as a unit since the terminal I/O driver always sends 

780 job-control stop signals to all processes in the process group. 

781 To continue a stopped job, the shell sends the SIGCONT signal to the process 

782 group of the job. In addition, if the job is being continued in the foreground, the 

783 shell invokes tcsetpgrpO to place the job in the foreground before sending 

784 SIGCONT. Otherwise, the shell leaves itself in the foreground and reads addi- 

785 tional commands. 

786 There is additional flexibility in the POSIX.l job-control facilities that allows devi- 

787 ations from the typical interface. Clearing the TOSTOP terminal flag (see 7 . 1 . 2 . 5 ) 

788 allows background jobs to perform writeO functions without stopping. The same 

789 effect can be achieved on a per-process basis by having a process set the signal 

790 action for SIGTTOU to SIG_IGN. 
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791 Note that the terms job and process group can be used interchangeably. A login 

792 session that is not using the job control facilities can be thought of as a large col- 

793 lection of processes that are all in the same job (process group). Such a login ses- 

794 sion may have a partial distinction between foreground and background 

795 processes; that is, the shell may choose to wait for some processes before continu- 

796 ing to read new commands and may not wait for other processes. However, the 

797 terminal I/O driver will consider all these processes to be in the foreground since 

798 they are all members of the same process group. 

799 In addition to the basic job-control operations already mentioned, a job-control- 

800 cognizant shell needs to perform the following actions: 

sol When a foreground (not background) job stops, the shell must sample and 

802 remember the current terminal settings so that it can restore them later when it 

803 continues the stopped job in the foreground [via the tegetattr () and tcsetattrl) 

804 functions], 

805 Because a shell itself can be spawned from a shell, it must take special action to 

806 ensure that subshells interact well with their parent shells. 

807 A subshell can be spawned to perform an interactive function (prompting the ter- 

808 minal for commands) or a noninteractive function (reading commands from a file). 

809 When operating noninteractively, the job-control shell will refrain from perform- 

8 10 ing the job-control specific actions described above. It will behave as a shell that 

811 does not support job control. For example, all jo&s will be left in the same process 

812 group as the shell, which itself remains in the process group established for it by 

813 its parent. This allows the shell and its children to be treated as a single job by a 

814 parent shell, and they can be affected as a unit by terminal keyboard signals. 

sis An interactive subshell can be spawned from another job-control-cognizant shell 

816 in either the foreground or background. (For example, from the C Shell, the user 

817 can execute the command, esh s.) Before the subshell activates job control by 

bis calling setpgidi) to place itself in its own process group and tcsetpgrp( ) to place its 

819 new process group in the foreground, it needs to ensure that it has already been 

820 placed in the foreground by its parent. (Otherwise, there could be multiple job- 

821 control shells that simultaneously attempt to control mediation of the terminal.) 

822 To determine this, the shell retrieves its own process group via getpgrpO and the 

823 process group of the current foreground job via tegetpgrp (). If these are not equal, 

824 the shell sends SIGTTIN to its own process group, causing itself to stop. When 

826 continued later by its parent, the shell repeats the process-group check. When 

826 the process groups finally match, the shell is in the foreground and it can proceed 

827 to take control. After this point, the shell ignores all the job-control stop signals 

828 so that it does not inadvertently stop itself. 

829 Implementing Job Control Applications 

830 Most applications do not need to be aware of job-control signals and operations; 

831 the intuitively correct behavior happens by default. However, sometimes an 

832 application can inadvertently interfere with normal job-control processing, or an 

833 application may choose to overtly effect job control in cooperation with norma 

834 shell procedures. 

835 An application can inadvertently subvert job-control processing by “blindly alter- 

836 ing the handling of signals. A common application error is to learn how many 
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signals the system supports and to ignore or catch them all. Such an application 
makes the assumption that it does not know what this signal is, but knows the 
right handling action for it. The system may initialize the handling of job-control 
stop signals so that they are being ignored. This allows shells that do not support 
job control to inherit and propagate these settings and hence to be immune to stop 
signals. A job-control shell will set the handling to the default action and pro- 
pagate this, allowing processes to stop. In doing so, the job-control shell is taking 
responsibility for restarting the stopped applications. If an application wishes to 
catch the stop signals itself, it should first determine their inherited handling 
states. If a stop signal is being ignored, the application should continue to ignore 
it. This is directly analogous to the recommended handling of SIGINT described 111 
the UNIX Programmer’s Manual (B4J). 

If an application is reading the terminal and has disabled the interpretation of 
special characters (by clearing the ISIG flag), the terminal I/O driver will not send 
SIGTSTP when the suspend character is typed. Such an application can simulate 
the effect of the suspend character by recognizing it and sending SIGTSTP to its 
process group as the terminal driver would have done. Note that the signal is 
sent to the process group, not just to the application itself; this ensures that other 
processes in the job also stop. (Note also that other processes in the job cou d be 
children, siblings, or even ancestors.) Applications should not assume that the 
suspend character is control-Z (or any particular value); they should retrieve the 
current setting at startup. 

Implementing Job Control Systems 

The intent in adding 4.2BSD-style job control functionality was to adopt the neces- 
sary 4.2BSD programmatic interface with only minimal changes to resolve syntac- 
tic or semantic conflicts with System V or to close recognized secunty holes, lhe 
goal was to maximize the ease of providing both conforming implementations and 
Conforming POSIX.l Applications. 

Discussions of the changes can be found in the clauses that discuss the specific 
interfaces. See B.3.2.1, B.3.2.2, B.3.3.1.1, B.3.3.2, B.3.3.4, B.4.3.1, B.4.3.3, 
B.7.1.1.4, and B.7.2.4. 

It is only useful for a process to be affected by job-control signals if it is the des- 
cendant of a job-control shell. Otherwise, there will be nothing that continues the 
stopped process. Because a job-control shell is allowed, but not required, by 
P0SIX1, an implementation must provide a mechanism that shields processes 
from job-control signals when there is no job-control shell. The usual method is 
for the system initialization process (typically called init), which is the ancestor 
of all processes, to launch its children with the signal handling action set to 
SIG_IGN for the signals SIGTSTP, SIGTTIN, and SIGTTOU. Thus, all login shells 
start with these signals ignored. If the shell is not job-control cognizant then it 
should not alter this setting and all its descendants should inherit the same 
ignored settings. At the point where a job-control shell is launched, it resets the 
signal handling action for these signals to be SIG_DFL for its children and (by 
inheritance) their descendants. Also, shells that are not job-control cognizant wi l 
not alter the process group of their descendants or of their controlling termina , 
this has the effect of making all processes be in the foreground (assuming the 
shell is in the foreground). While this approach is valid, POSIX.1 added the con- 
cept of orphaned process groups to provide a more robust solution to this problem. 
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All processes in a session managed by a shell that is not job-control cognizant are 
in an orphaned process group and are protected from stopping. 

POSIX. 1 does not specify how controlling terminal access is affected by a user log- 
ging out (that is, by a controlling process terminating). 4.2BSD uses the 
v hangup () function to prevent any access to the controlling terminal through file 
descriptors opened prior to logout. System V does not prevent controlling termi- 
nal access through file descriptors opened prior to logout (except for the case of 
the special file, /dev/ tty). Some implementations choose to make processes 
immune from job control after logout (that is, such processes are always treated 
as if in the foreground); other implementations continue to enforce 
foreground/background checks after logout. Therefore, a Conforming POSIX. 1 
Application should not attempt to access the controlling terminal after logout 
since such access is unreliable. If an implementation chooses to deny access to a 
controlling terminal after its controlling process exits, POSIX.1 requires a certain 
type of behavior (see 7.1. 1.3). 

♦kernel: See system call . 

♦library routine: See system call. 

♦logical device: Implementation defined. 

♦mount point: The directory on which a mounted file system is mounted. This 
term, like mount{) and umount (), was not included because it was implementa- 
tion defined. 

♦mounted file system: See file system. 

♦native implementation: This refers to an implementation of POSIX.1 that 
interfaces directly to an operating-system kernel. See also hosted implementation 
and cooperating implementation. A similar concept is a native UNIX system, 
which would be a kernel derived from one of the original UNIX system products. 

open file description: An open file description, as it is currently named, 
describes how a file is being accessed. What is currently called a file descriptor is 
actually just an identifier or “handle”; it does not actually describe anything. 

The following alternate names were discussed: 

For open file description : 

open instance, file access description, open file information, and file 
access information. 

For file descriptor: 

file handle, file number [c.f., fileno()]. Some historical implementations 
use the term file table entry. 

orphaned process group: Historical implementations have a concept of an 
orphaned process, which is a process whose parent process has exited. When job 
control is in use, it is necessary to prevent processes from being stopped in 
response to interactions with the terminal after they no longer are controlled by a 
job-control-cognizant program. Because signals generated by the terminal are 
sent to a process group and not to individual processes, and because a signal may 
be provoked by a process that is not orphaned, but sent to another process that is 
orphaned, it is necessary to define an orphaned process group. The definition 
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929 assumes that a process group will be manipulated as a group and that the job- 
pso control-cognizant process controlling the group is outside of the group and is the 

931 parent of at least one process in the group [so that state changes may be reported 

932 via waitpidi)]. Therefore, a group is considered to be controlled as long as at least 

933 one process in the group has a parent that is outside of the process group, but 

934 within the session. 

935 This definition of orphaned process groups ensures that a session leader’s process 

936 group is always considered to be orphaned, and thus it i9 prevented from stopping 

937 in response to terminal signals. 

938 *passwd file: Implementation defined; see B.9. 

939 parent directory: There may be more than one directory entry pointing to a 

940 given directory in some implementations. The wording here identifies that 

941 exactly one of those is the parent directory. In 2.3.6, dot-dot is identified as the 

942 way that the unique directory is. identified. (That is, the parent directory is the 

943 one to which dot-dot points.) In the case of a remote file system, if the same file 

944 system is mounted several times, it would appear as if they were distinct file sys- 

945 terns (with interesting synchronization properties). 

946 pipe: It proved convenient to define a pipe as a special case of a FIFO even 

947 though historically the latter was not introduced until System III and does not 

948 exist at all in 4.3BSD. 

949 portable filename qharacter set: The encoding of this character set is not 
960 specified — specifically, ASCII is not required. But the implementation must pro- 
951 vide a unique character code for each of the printable graphics specified by 
962 POSIX.1. See also B.2.3.5. 


963 Situations where characters beyond the portable filename character set (or histor- 

954 ically ASCII or ISO/IEC 646 (1)) would be used (in a context where the portable 

965 filename character set or ISO/IEC 646 {1} is required by POSIX.1) are expected to 

956 be common. Although such a situation renders the use technically noncompliant, 

957 mutual agreement among the users of an extended character set will make such 

968 use portable between those users. Such a mutual agreement could be formalized 

969 as an optional extension to POSIX.1. (Making it required would eliminate too 

960 many possible systems, as even those systems using ISO/IEC 646 (1) as a base 

961 character set extend their character sets for Western Europe and the rest of the 

962 world in different ways.) 

963 Nothing in POSIX.1 is intended to preclude the use of extended characters where 

964 interchange is not required or where mutual agreement is obtained. It has been 

965 suggested that in several places “should” be used instead of “shall.” Because (in 

966 the worst case) use of any character beyond the portable filename character set 

967 would render the program or data not portable to all possible systems, no exten- 

968 sions are permitted in this context. 

969 regular file: POSIX.1 does not intend to preclude the addition of structuring 

970 data (e.g., record lengths) in the file, as long as such data is not visible to an 

971 application that uses the features described in POSIX.1. 



m 


972 root directory: This definition permits the operation of chroot.(), even though 

973 that function is not in POSIX.1. See also file hierarchy. 
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974 ‘root file system: Implementation defined. 

975 *root of a file system: Implementation defined. See mount point. 

976 seconds since the Epoch: The formula here is not precisely correct for leap | 

977 centuries. See the discussion for Epoch for further details. | 

978 signal: The definition implies a double meaning for the term. Although a signal 

979 is an event, common usage implies that a signal is an identifier of the class of 
9so event. 

98 1 ‘system call: The distinction between a system call and a library routine is an 

982 implementation detail that may differ between implementations and has thus 

983 been excluded from POSIX.l. See “Interface, Not Implementation” in the Intro- 

984 duction. 

985 * super-user: This concept, with great historical significance to UNIX system 

986 users, has been replaced with the notion of appropriate privileges. 

987 B.2.2.3 Abbreviations | 

988 There is no additional rationale provided for this subclause. ! 

989 B.2.3 General Concepts 

990 B.2.3. 1 extended security controls: Allowing an implementation to define 

991 extended security controls enables the use of POSIX. 1 in environments that 

992 require different or more rigorous security than that provided in POSIX.l. Exten- 

993 sions are allowed in two areas: privilege and file access permissions. The seman- 

994 tics of these areas have been defined to permit extensions with reasonable, but 

995 not exact, compatibility with all existing practices. For example, the elimination 

996 of the super-user definition precludes identifying a process as privileged or not by 

997 virtue of its effective user ID. 

998 B.2.3.2 file access permissions: A process should not try to anticipate the 

999 result of an attempt to access data by a priori use of these rules. Rather, it should 

1000 make the attempt to access data and examine the return value (and possibly 

1001 errno as well), or use access(). An implementation may include other security 

1002 mechanisms in addition to those specified in POSIX.l, and an access attempt may 

1003 fail because of those additional mechanisms, even though it would succeed accord- 

1004 ing to the rules given in this subclause. (For example, the user’s security level | 

loos might be lower than that of the object of the access attempt.) The optional supple- 

1006 mentary group IDs provide another reason for a process to not attempt to antici- 

1007 pate the result of an access attempt. 

1008 B.2.3.3 file hierarchy: Though the file hierarchy is commonly regarded to be a 

1009 tree, POSIX. 1 does not define it as such for three reasons: 

1010 (1) Links may join branches. 

ion (2) In some network implementations, there may be no single absolute root 
1012 directory. See pathname resolution . 
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1013 (3) With symbolic links (found in 4.3BSD), the file system need not be a tree 

1014 or even a directed acyclic graph. 

ioi6 B.2.3.4 file permissions: Examples of implementation-defined constraints that 
loir, may deny access are mandatory labels and access control lists. 

ion B.2.3.5 filename portability: Historically, certain filenames have been 

1018 reserved. This list includes core, /etc/passwd, etc. Portable applications 

1019 should avoid these. 

1020 Most historical implementations prohibit case folding in filenames; i.e., treating | 

1021 upper- and lowercase alphabetic characters as identical. However, some consider 

1022 case folding desirable: 

1023 — For user convenience 

1024 — For ease of implementation of the POSIX.l interface as a hosted system on 

1025 some popular operating systems, which is compatible with the goal of mak- 

1026 ing the POSIX.l interface broadly implementable (see “Broadly Implement- 

1027 able” in the Introduction) 

1028 Variants such as maintaining case distinctions in filenames, but ignoring them in 

1 1029 comparisons, have been suggested. Methods of allowing escaped characters of the 

1030 case opposite the default have been proposed 

1031 Many reasons have been expressed for not allowing case folding, including: 

1032 (1) No solid evidence has been produced as to whether case sensitivity or 

1033 case insensitivity is more convenient for users. 

1034 (2) Making case insensitivity a POSIX. 1 implementation option would be 

1035 worse than either having it or not having it, because 

1036 (a) More confusion would be caused among users. 

1037 (b) Application developers would have to account for both cases in their 

1038 code. 

1039 (c) POSIX.1 implementors would still have other problems with native 

1040 file systems, such as short or otherwise constrained filenames or 

1041 pathnames, and the lack of hierarchical directory structure. 

1042 (3) Case folding is not easily defined in many European languages, both 

1043 because many of them use characters outside the USASCII alphabetic set, 

1044 and because 

1045 (a) In Spanish, the digraph 11 is considered to be a single letter, the 

1046 capitalized form of which may be either LI or ll, depending on con- 

1047 text. 

1048 (b) In French, the capitalized form of a letter with an accent may or 

1049 may not retain the accent depending on the country in which it is 

1050 written. 

1051 (c) In German, the sharp ess may be represented as a single character 

1052 resembling a Greek beta (p) in lowercase, but as the digraph ss in 

1053 uppercase. 




B .2 Definitions and General Requirements 


209 


ISO/IEC 9946-1: 1990 
IEEE Std 1003.1-1990 


INFORMATION TECHNOLOGY— POSIX 


1 

! 


1054 (d) In Greek, there are several lowercase forms of some letters; the one 

loss to use depends on its position in the word. Arabic has similar rules. 

1056 ( 4 ) Many East Asian languages, including Japanese, Chinese, and Korean, 

1057 do not distinguish case and are sometimes encoded in character sets that 

loss use more than one byte per character. 

1069 ( 5 ) Multiple character codes may be used on the same machine simultane- 

1060 ously. There are several ISO character sets for European alphabets. In 

1061 Japan, several Japanese character codes are commonly used together, 

1062 sometimes even in filenames; this is evidently also the case in China. To 

1063 handle case insensitivity, the kernel would have to at least be able to dis- 

1064 tinguish for which character sets the concept made sense. 

1065 ( 6 ) The file system implementation historically deals only with bytes, not 

1066 with characters, except for slash and the null byte. 

1067 ( 7 ) The purpose of POSIX.l is to standardize the common, existing definition 

1068 (see “Application Oriented” in the Introduction) of the UNIX system pro- 

1069 gramming interface, not to change it. Mandating case insensitivity 

1070 would make all historical implementations nonstandard. 

1071 ( 8 ) Not only the interface, but also application programs would need to 

1072 change, counter to the purpose of having minimal changes to existing 

1073 application code. 

1074 ( 9 ) At least one of the original developers of the UNIX system has expressed - 

1075 objection in the strongest terms to either requiring case insensitivity or 

1076 making it an option, mostly on the basis that POSIX.l should not hinder 

1077 portability of application programs across related implementations in 

1078 order to allow compatibility with unrelated operating systems. 

1079 Two proposals were entertained regarding case folding in filenames: 

1080 — Remove all wording that previously permitted case folding. 

1081 Rationale: Case folding is inconsistent with portable filename character set 

1082 definition and filename definition (all characters except slash and null). No 

1083 known implementations allowing all characters except slash and null also 

1084 do case folding. 

1086 — Change “though this practice is not recommended:” to “although this prac- 

1086 tice is strongly discouraged.” 

1087 Rationale: If case folding must be included in POSIX.l, the wording should 

1088 be stronger to discourage the practice. 

1089 The consensus selected the first proposal. Otherwise, a portable application | 

1090 would have to assume that case folding would occur when it was not wanted, but 

1091 that it would not occur when it was wanted. 

1092 B.2.3.6 file times update: This subclause reflects the actions of historical | 

1093 implementations. The times are not updated immediately, but are only marked 

1094 for update by the functions. An implementation may update these times 
1096 immediately. 
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1096 The accuracy of the time update values is intentionally left unspecified so that 

1097 systems can control the bandwidth of a possible covert channel. 

1098 The wording was carefully chosen to make it clear that there is no requirement | 

1099 that the conformance document contain information that might incidentally affect 

1100 file update times. Any function that performs pathname resolution might update 

1101 several stjatime fields. Functions such as getpwnam () and getgrnam () might 
no2 update the st_atime field of some specific file or files. It is intended that these are 
nos not required to be documented in the conformance document, but they should 
H04 appear in the system documentation. 

nos B.2.3.7 pathname resolution: What the filename dot-dot refers to relative to 
lioo the root directory is implementation defined. In Version 7 it refers to the root 
1107 directory itself; this is the behavior mentioned in the standard. In some 
nos networked systems the construction / . . /hostname/ is used to refer to the root 

1109 directory of another host, and POSIX.l permits this behavior. 

1110 Other networked systems use the construct //hostname for the same purpose; 
mi i.e., a double initial slash is used. There is a potential problem with existing 
ni2 applications that create full pathnames by talcing a trunk and a relative path- 

1113 name and making them into a single airing separated by /, because they can 

1114 accidentally create networked pathnames when the trunk is /. This practice is 
ins not prohibited because such applications can be made to conform by simply 

1116 changing to use // as a separator instead of /: 

1117 ( 1 ) If the trunk is /, the full path name will begin with /// (the initial / and 

me the separator //). This is the same as /, which is what is desired. (This 

1119 is the general case of making a relative pathname into an absolute one by 

1120 prefixing with // / instead of /.) 

1121 ( 2 ) If the trunk is /A, the result is /A/ / . . . ; since nonleading sequences of 

1122 two or more slashes are treated as a single slash, this is equivalent to the 

1123 desired /A/ . . 

1124 (3) If the trunk is //A, the implementation-defined semantics will apply. 

1126 (The multiple slash rule would apply.) 

1126 Application developers should avoid generating pathnames that start with “/ /”. 

1127 Implementations are strongly encouraged to avoid using this special interpreta- 

1128 tion since a number of applications currently do not follow this practice and may 

1129 inadvertently generate “//...”. 

1130 The term root directory is only defined in POSIX. 1 relative to the process. In some 

1131 implementations, there may be no absolute root directory. The initialization of 

1132 the root directory of a process is implementation defined. 

1133 B.2.4 Error Numbers 

1134 The definition of errno in POSIX.l is stricter than that in the C Standard ( 2 ). The | 

1135 C Standard ( 2 ) merely requires that it be an assignable lvalue. The POSIX. 1 | 

1136 extern int errno meets that requirement and supports historical usage as well. | 
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1137 Checking the value of errno alone is not sufficient to determine the existence or 
lias type of an error, since it is not required that a successful function call clear errno. 

1139 The variable errno should only be examined when the return value of a function 

1140 indicates that the value of errno is meaningful. In that case, the function is 

11 4 1 required to set the variable to something other than zero. 

1142 A successful function call may set the value of errno to zero, or to any other value 

1143 (except where specifically prohibited; see B. 5 . 4 . 1 ). But it is meaningless to do so, 

11 44 since the value of errno is undefined except when the description of a function 
1146 explicitly states that it is set, and no function description states that it should be 

1146 set on a successful call. Most functions in most implementations do not change 

1147 errno on successful completion. Exceptions are isatty () and ptrace (). The latter is 
H 48 not in POSIX. 1 , but is widely implemented and clears errno when called. The 

1149 value of errno is not defined unless all signal handlers that use functions that 

1150 could change errno save and restore it. 

1161 POSIX. 1 requires (in the Errors subclauses of function descriptions) certain error | 

1152 values to be set in certain conditions because many existing applications depend | 

1153 on them. Some error numbers, such as [EFAULT], are entirely implementation 

1164 defined and are noted as such in their description in 2 . 4 . This subclause other- | 
H55 wise allows wide latitude to the implementation in handling error reporting. I 

1156 Some of the Errors clauses in POSIX.l have two subclauses. The first: I 

1167 “If any of the following conditions occur, the foo() function shall 

1168 return -1 and set errno to the corresponding value:” 

1159 could be called the “mandatory” subclause. The second: I 

H 6 o “For each of the following conditions, when the condition is detected, 

1161 the foo{) function shall return -1 and set errno to the cprresponding 

1162 value:” 


i 


H 63 could be informally known as the “optional” subclause. This latter subclause has | 

H 64 evolved in meaning over time. In early drafts, it was only used for error condi- | 

lies tions that could not be detected by certain hardware configurations, such as the 

nee [ EFAULT] error, as described below. The subclause recently has also added condi- | 

1167 tions associated with optional system behavior, such as job control errors. | 

lies Attempting to infer the quality of an implementation based on whether it detects | 

H69 such conditions is not useful. | 

1170 Following each one-word symbolic name for an error, there is a one-line tag, 
H 7 i which is followed by a description of the error. The one-line tag is merely a 
H72 mnemonic or historical referent and is not part of the specification of the error. 
1173 Many programs print these tags on the standard error stream [often by using the 
U 74 C Standard { 2 } perror() function] when the corresponding errors are detected, but 
1175 POSIX. 1 does not require this action. 


i 

* 

i 

i 


1176 [EFAULT] Most historical implementations do not catch an error and set 
H77 errno when an invalid address is given to the functions wait { ), 

H78 time 0 , or timesi). Some implementations cannot reliably detect 

H79 an invalid address. And most systems that detect invalid 

1180 addresses will do so only for a system call, not for a library 

1181 routine. 
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1182 [EINTR] POSIX .1 prohibits conforming implementations from restarting 

1183 interrupted system calls. However, it does not require that 

H 84 [EINTR] be returned when another legitimate value may be 

U 86 substituted; e.g., a partial transfer count when readO or write 0 

1186 are interrupted. This is only given when the signal catching 

1187 function returns normally as opposed to returns by mechanisms 

H 88 like longjmp ( ) or siglongjmp ( ). 

1189 [ENOMEM] The term main memory is not used in POSIX.l because it is 

H 90 implementation defined. 

1191 [ENOTTY] The symbolic name for this error is derived from a time when 

1192 device control was done by ioctli) and that operation was only 

1193 permitted on a terminal interface. The term “TTY” is derived 

1194 from teletypewriter , the devices to which this error originally 

H 96 applied. 

1196 [EPIPE] This condition normally generates the signal SIGPIPE; the error 

1197 is returned if the signal does not terminate the process. 

1198 [EROFS] In historical implementations, attempting to unlink () or 

H 99 rmdir() a mount point would generate an [EBUSY] error. An 

1200 implementation could be envisioned where such an operation 

1201 could be performed without error. In this case, if either the 

1202 directory entry or the actual data structures reside on a read- 

1203 only file system, [EROFS] is the appropriate error to generate. 

1204 (For example, changing the link count of a file on a read-only 

1205 file system could not be done, as is required by unlinkQ , and 

1206 thus an error should be reported.) 

1207 Two error numbers, [EDOM] and [ERANGE], were added to this subclause pri- | 

1208 marily for consistency with the C Standard ( 2 ). | 

1209 B. 2.5 Primitive System Data Types 

1210 The requirement that additional types defined in this subclause end in “_t” was | 

1211 prompted by the problem of namespace pollution (see B. 2 . 7 . 2 ). It is difficult to 

1212 define a type (where that type is not one defined by POSIX.l) in one header file 

1213 and use it in another without adding symbols to the namespace of the program. 

1214 To allow implementors to provide their own types, all POSIX .1 conforming applica- 
ble tions are required to avoid symbols ending in “_t”, which permits the implementor 

1216 to provide additional types. Because a major use of types is in the definition of 

1217 structure members, which can (and in many cases must) be added to the struc- 

1218 tures defined in POSIX. 1 , the need for additional types is compelling. 

1219 The types such as ushort and ulong, which are in common usage, are not defined 

1220 in POSIX .1 (although ushort _t would be permitted as an extension). They can be 

1221 added to <sys/types .h> using a feature test macro (see 2 . 7 . 2 ). A suggested 

1222 symbol for these is _SYSIII. Similarly, the types like u. short would probably be 

1223 best controlled by _BSD. 
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This type may be made large enough to accommodate host- 
locality considerations of networked systems. 

This type must be arithmetic. Earlier drafts allowed this to be 
nonarithmetic (such as a structure) and provided a samefile () 
function for comparison. 

Some implementations had separated gidjt from uid_t before 
POSIX. 1 was completed. It would be difficult for them to 
coalesce them when it was unnecessary. Additionally, it is 
quite possible that user IDs might be different than group IDs 
because the user ID might wish to span a heterogeneous net- 
work, where the group ID might not. 

For current implementations, the cost of having a separate 
gidjt will be only lexical. 

This type was chosen so that implementations could choose the 
appropriate integral type, and for compatibility with the 
C Standard (2). 4.3BSD uses unsigned short and the SVID uses 
ushort, which is the same. Historically, only the low-order six- 
teen bits are significant. 

This type was introduced in place of short for stjilink (see 
5.6.1) in response to an objection that short was too small. 

This type is used only in Iseek (), fcntl() , and <sys/stat . h>. 
Many implementations would have difficulties if it were defined 
as anything other than long. Requiring an integral type limits 
the capabilities of IseekO to four gigabytes. See the description 
of IreadO in B.6.4. Also, the C Standard {2} supplies routines 
that use larger types: see fgetposO and fsetposO in B.6.5.3. 

The inclusion of this symbol was controversial because it is tied 
to the issue of the representation of a process ID as a number. 
From the point of view of a portable application, process IDs 
should be “magic cookies” 2 * that are produced by calls such as 
fork j(), used by calls such as waitpidO or killO, and not other- 
wise analyzed (except that the sign is used as a flag for certain 
operations). 

The concept of a (PID_MAX) value interacted with this in early 
drafts. Treating process IDs as an opaque type both removes 
the requirement for (PID_MAX) and allows systems to be more 
flexible in providing process IDs that span a large range of 
values, or a small one. 


1263 2) An historical term meaning: “An opaque object, or token, of determinate size, whose significance 

1264 is known only to the entity which created it. An entity receiving such a token from the 

1265 generating entity may only make such use of the ‘cookie’ as is defined and permitted by the 

1266 supplying entity." 
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Since the values in uidjt , gidj, and pidjt will be numbers gen- 
erally, and potentially both large in magnitude and sparse, 
applications that are based on arrays of objects of this type are 
unlikely to be fully portable in any case. Solutions that treat 
them as magic cookies will be portable. 

(CHILD_MAX) precludes the possibility of a “toy implementa- 
tion,” where there would only be one process. 

ssizejt This is intended to be a signed analog of sizejt. The wording is 

such that an implementation may either choose to use a longer 
type or simply to use the signed version of the type that under- 
lies size_t. All functions that return ssizej IreadO and write 01 
describe as “implementation defined” the result of an input 
exceeding (SSIZE_MAX). It is recognized that some implemen- 
tations might have int s that are smaller than size_t. A port- 
able application would be constrained not to perform I/O in 
pieces larger than (SSIZE_MAX), but a portable application 
using extensions would be able to use the full range if the 
implementation provided an extended range, while still having 
a single type-compatible interface. 

The symbols sizej and ssizejt are also required in 
<unistd . h> to minimize the changes needed for calls to readO 
and write 0- Implementors are reminded that it must be possi- 
ble to include both <sys/ types . h> and <unistd.h> in the 
same program (in either order) without error. 

uid_t Before the addition of this type, the data types used to 

represent these values varied throughout early drafts. The 
<sys/stat .h> header defined these values as type short, the 
<passwd.h> file (now <pwd.h> and <grp.h>) used an int, 
and getuidO returned an int. In response to a strong objection 
to the inconsistent definitions, all the types to were switched to | 
uidjt. j 

In practice, those historical implementations that use varying 
types of this sort can typedef uidjt to short with no serious 
consequences. 

The problem associated with this change concerns object com- 
patibility after structure size changes. Since most implementa- 
tions will define uidj as a short, the only substantive change 
will be a reduction in the size of the passwd structure. Conse- 
quently, implementations with an overriding concern for object 
compatibility can pad the structure back to its current size. For 
that reason, this problem was not considered critical enough to 
warrant the addition of a separate type to POSIX. 1. 

The types uidj and gid_t are magic cookies. There is no 
(UID_MAX) defined by POSIX. 1, and no structure imposed on 
uidj and gidj other than that they be positive arithmetic 
types. (In fact, they could be unsigned char.) There is no max- 
imum or minimum specified for the number of distinct user or 
group IDs. 
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B.2.6 Environment Description 

The variable environ is not intended to be declared in any header, but rather to be | 
declared by the user for accessing the array of strings that is the environment, j 
This is the traditional usage of the symbol. Putting it into a header could break | 
some programs that use the symbol for their own purposes. i 

LC_* The description of the environment variable names starting 

with the characters “LC_” acknowledges the fact that the inter- 
faces presented in the current version of POSIX.1 are not com- 
plete and may be extended as new international functionality is 
required. In the C Standard {2}, names preceded by “LC_” are | 
reserved in the name space for future categories. 

To avoid name clashes, new categories and environment vari- 
ables are divided into two classifications: implementation 
independent and implementation dependent. 

Implementation-independent names will have the following 
format: 

LC _NAME 

where NAME is the name of the new category and environment 
variable. Capital letters must be used for implementation- 
independent names. 

Implementation-dependent names must be in lowercase letters, 
as below: 


PATH Many historical implementations of the Bourne shell do not 

interpret a trailing colon to represent the current working 
directory and are thus nonconforming. The C Shell and the 
KornShell conform to POSIX.1 on this point. The usual name of 
dot may also be used to refer to the current working directory. 

TZ See 8.1.1 for an explanation of the format. 

LOGNAME 4.3BSD uses the environment variable USER for this purpose. 

In most implementations, the value of such a variable is easily 
forged, so security-critical applications should rely on other 
means of determining user identity. LOGNAME is required to 
be constructed from the portable filename character set for rea- 
sons of interchange. No diagnostic condition is specified for 
violating this rule, and no requirement for enforcement exists. 
The intent of the requirement is that if extended characters are 
used, the “guarantee” of portability implied by a standard is 
voided. (See also B.2.2.2.) 

The following environment variables have been used historically as indicated. 
However, such use was either so variant as to not be amenable to standardization 
or to be relevant only to other facilities not specified in POSIX.1, and they have 
therefore been excluded. They may or may not be included in future POSIX stan- 
dards. Until then, writers of conforming applications should be aware that 
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details of the use of these variables are likely to vary in different contexts. 

IFS Characters used as field separators. 

MAIL System mailer information. 

PS1 Prompting string for interactive programs. 

PS2 Prompting string for interactive programs. 

SHELL The shell command interpreter name. 

B.2.7 C Language Definitions 

The construct <name . h> for headers is also taken from the C Standard {2}. 

B.2.7.1 Symbols From the C Standard 

The reservation of identifiers is paraphrased from the C Standard (2). The text is | 
included because it needs to be part of POSIX.1, regardless of possible changes in | 
future versions of the G Standard (2). The reservation of other namespaces is par- | 
ticularly for <errno . h>. 

These identifiers may be used by implementations, particularly for feature test 
macros. Implementations should not use feature test macro names that might be 
reasonably used by a standard. 

The requirement for representing the number of clock ticks in 24 h refers to the | 
interval defined by POSIX.1, not to the interval defined by the C Standard (2). | 

Including headers more than once is a reasonably common practice, and it should 
be carried forward from the C Standard {2}. More significantly, having definitions 
in more than one header is explicitly permitted. Where the potential declaration 
is “benign” (the same definition twice) the declaration can be repeated, if that is 
permitted by the compiler. (This is usually true of macros, for example.) In those 
situations where a repetition isliot benign (e.g., typedefs), conditional compilation 
must be used. The situation actually occurs both within the C Standard {2} and 
within POSIX.1: time_t should be in <sys/types .h>, and the C Standard (2) 
mandates that it be in ctime . h>. POSIX.1 requires using <sys/types . h> with 
ctime . h> because of the common-usage environment. 

B.2.7.2 POSIX.1 Symbols 

This subclause addresses the issue of “namespace pollution.” The C Standard (2) | 

requires that the namespace beyond what it reserves not be altered except by 
explicit action of the application writer. This subclause defines the actions to add | 
the POSIX.1 symbols for those headers where both the C Standard {2} and POSIX.1 j 
need to define symbols. Where there are nonoverlapping uses of headers, there is 
no problem. 

The list of symbols defined in the C Standard (2) is summarized in the rationale | 
associated with Annex C. I 

Implementors should note that the requirement on type conversion disallows | 
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1397 using an older declaration as a prototype and in effect requires that the number of | 

1398 arguments in the prototype match that given in POSIX 1. I 

1399 When headers are used to provide symbols, there is a potential for introducing 

1400 symbols that the application writer cannot predict. Ideally, each header should 

1401 only contain one set of symbols, but this is not practical for historical reasons. 

1402 Thus, the concept of feature test macros is included. This is done in a general 

non manner because it is expected that future additions to POSIX.l and other related 

1404 standards will have this same problem. (Future standards not constrained by 

1405 historical practice should avoid the problem by using new header files rather than 

1406 using ones already extant.) 

1407 This idea is split into two subclauses: 2.7.2. 1 covers the case of the C Standard | 

1408 (2) conformant systems, where the requirements of the C Standard {2} are that 

1409 unless specifically requested the application will not see any other symbols, and 

1410 “Common Usage,” where the default set of symbols is not well controlled and 

1411 backwards compatibility is an issue. 

1412 The common usage case is the more difficult to define. In the C Standard {2} case, 

1413 each feature test macro simply adds to the possible symbols. In common usage, 

1414 _POSIX_SOURCE is a special case in that it reduces the set to the sum of the 

1416 C Standard {2} and P0SIX1. (The developers of the C Standard {2} will determine | 

1416 if they want a similar macro to limit the features to just the C Standard {2}; the 

1417 wording permits this because under those circumstances _POSIX_SOURCE would 

1418 be just another ordinary feature test macro. The only order requirement is 

14 19 “before headers.”) 

1420 If _P0SIXJ3OURCE is not defined in a common-usage environment, the user 

1421 presumably gets the same results as in previous releases. Some applications may 

1422 today be conformant without change, so they would continue to compile as long as 

1423 common usage is provided. When the C Standard (2) is the default they will have 

1424 to change (unless they are already C Standard {2} conformant), but this can be 

1425 done gradually. 

1426 Note that the net result of defining _POSIX_SOURCE at the beginning of a pro- 

1427 gram is in either case the same: the implementation-defined symbols are only 

1428 visible if they are requested. (But if _POSIX_SOURCE is not used, the implemen- 

1429 tation default, which is probably backwards compatible, determines their 

1430 visibility.) 

1431 The area of namespace pollution versus additions to structures is difficult because 

1432 of the macro structure of C. The following discussion summarizes all the various 

1433 problems with and objections to the issue. 

1434 Note the phrase “user defined macro.” Users are not permitted to define macro 
1436 names (or any other name) beginning with __[A-Z_]. Thus, the conflict cannot 

1436 occur for symbols reserved to the vendor’s namespace, and the permission to add 

1437 fields automatically applies, without qualification, to those symbols. 

1438 (1) Data structures (and unions) need to be defined in headers by implemen- 

1439 tations to meet certain requirements of POSIX.l and the C Standard (2). 

1440 (2) The structures defined by POSIX1 are typically minimal, and any practi- 

1441 cal implementation would wish to add fields to these structures either to 

1442 hold additional related information or for backwards compatibility (or 
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both). Future standards (and de facto standards) would also wish to add 
to these structures. Issues of field alignment make it impractical (at 
least in the general case) to simply omit fields when they are not defined 
by the particular standard involved. 

Struct dirent is an example of such a minimal structure (although one 
could argue about whether the other fields need visible names). The 
stjrdev field of most implementations’ stat structure is a common exam- 
ple where extension is needed and where a conflict could occur. 

(3) Fields in structures are in an independent namespace, so the addition of 
such fields presents no problem to the C language itself in that such 
names cannot interact with identically named user symbols because 
access is qualified by the specific structure name. 

(4) There is an exception to this: macro processing is done at a lexical level. 
Thus, symbols added to a structure might be recognized as user-provided 
macro names at the location where the structure is declared. This only 
can occur if the user-provided name is declared as a macro before the 
header declaring the structure is included. The user’s use of the name 
after the declaration cannot interfere with the structure because the sym- 
bol is hidden and only accessible through access to the structure. 
Presumably, the user would not declare such a macro if there was an 
intention to use that field name. 

(5) Macros from the same or a related header might use the additional fields 
in the structure, and those field names might also collide with user mac- 
ros. Although this is a less frequent occurrence, since macros are 
expanded at the point of use, no constraint on the order of use of names 
can apply. 

(6) An “obvious” solution of using names in the reserved namespace and 
then redefining them as macros when they should be visible does not 
work because this has the effect of exporting the symbol into the general 
namespace. For example, given a (hypothetical) system-provided header 
<h . h>, and two parts of a C program in a . c and b . c: 

In header <h.h>: 

struct foo { 


#ifdef _FEATURE_TEST 

♦define i i; 

#endif 


In file a . c: 


♦include h.h 
extern int i; 


In file b. c: 
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extern int i; 

The symbol that the user thinks of as i in both files has an external 

name of " i" in a . c; the same symbol i in b . c has an external name 

"i" (ignoring any hidden manipulations the compiler might perform on 
the names). This would cause a mysterious name resolution problem 
when a . o and b . o are linked. 

Simply avoiding definition then causes alignment problems in the 
structure. 

A structure of the form 


1496 

1497 

1498 

1499 

1500 

1501 

1502 

1503 

1504 

1505 

1506 

1507 

! 1508 

1509 (7) A more workable solution would be to declare the structure: 

1510 

1511 

1512 

1513 

1514 

1515 

1516 

1617 However, if a macro (particularly one required by a standard) is to be 

1518 defined that uses this field, two must be defined: one that uses i, the 

1619 other that uses i. If more than one additional field is used in a macro 

1520 and they are conditional on distinct combinations of features, the com- 

1521 plexity goes up as 2 n . 

1522 All this leaves a difficult situation: vendors must provide very complex headers to 

1523 deal with what is conceptually simple and safe: adding a field to a structure. It is 

1524 the possibility of user-provided macros with the same name that makes this 

1525 difficult. 

1526 Several alternatives were proposed that involved constraining the user’s access to 

1527 part of the namespace available to the user (as specified by the C Standard (2)). 

1528 In some cases, this was only until all the headers had been included. There were 

1529 two proposals discussed that failed to achieve consensus: 


3truct foo ( 

#ifdef _FEATURE_TEST 
int i; 

♦ else 

int i; 

♦endif 

) 


struct foo ( 

union { 

int i; 

♦ifdef _FEATURE_TEST 
int i ; 

♦endif 

) ii; 

1 


does not work because the name of the logical field i is " ii. i", and 

introduction of a macro to restore the logical name immediately reintro- 
duces the problem discussed previously (although its manifestation 
might be more immediate because a syntax error would result if a recur- 
sive macro did not cause it to fail first). 
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1630 — Limiting it for the whole program. 

1531 — Restricting the use of identifiers containing only uppercase letters until 

1532 after all system headers had been included. It was also pointed out that 

1533 because macros might wish to access fields of a structure (and macro 

1634 expansion occurs totally at point of use) restricting names in this way 

1535 would not protect the macro expansion, and thus the solution was 

1536 inadequate. 

,1537 It was finally decided that reservation of symbols would occur, but as constrained. 

1538 The current wording also allows the addition of fields to a structure, but requires 

1539 that user macros of the same name not. interfere. This allows vendors to either: 

15 40 — Not create the situation [do not extend the structures with user-accessible 

1541 names or use the solution in (7) abovel or 

1542 — Extend their compilers to allow some way of adding names to structures 

1543 and macros safely. 

1544 There are at least two ways that the compiler might be extended: add new 

1545 preprocessor directives that turn off and on macro expansion for certain symbols 

1646 (without changing the value of the macro) and a function or lexical operation that 

1547 suppresses expansion of a word. The latter seems more flexible, particularly 

1548 because it addresses the problem in macros as well as in declarations. 

1549 The following seems to be a possible implementation extension to the C language 

1550 that will do this: any token that during macro expansion is found to be preceded 

1551 by three # symbols shall not be further expanded in exactly the same way as 

1552 described for macros that expand to their own name as in section 3. 8. 3. 4 of the 

1553 C Standard (2). A vendor may also wish to implement this as an operation that is 

1554 lexically a function, which might be implemented as 

1556 ♦define safe_name (x) ♦♦♦x 

1556 Using a function notation would insulate vendors from changes in standards until 

1557 such a functionality is standardized (if ever). Standardization of such a function 

1558 would be valuable because it would then permit third parties to take advantage of 

1559 it portably in software they may supply. 

1560 The symbols that are “explicitly permitted, but not required by this part of 

1561 ISO/IEC 9945” include those classified below. (That is, the symbols classified 

1662 below might, but are not required to, be present when _POSIX_SOURCE is 

1563 defined.) 

1564 — Symbols in 2.8 and 2.9 that are defined to indicate support for options or 

1666 limits that are constant at compile-time. 

1566 — Symbols in the namespace reserved for the implementation by the 

1567 C Standard {2}. 

1568 — Symbols in a namespace reserved for a particular type of extension (e.g., 

1569 type names ending with _t in <sys /types . h>). 

1570 — Additional members of structures or unions whose names do not reduce the 

1571 namespace reserved for applications (see B.2.7.2). 
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1672 The phrase “when that header is included” was chosen to allow any fine structure | 

1673 of auxiliary headers the implementor may choose to use, as long as the net result | 

1674 is as required. | 

1676 There are several common environments available today where a feature test 

1576 macro would be useful to applications programmers during the transition to 

1577 standard-conforming environments from certain common historical environments. 

1578 The symbols in Table B-l, derived from common porting bases and industry 

1579 specifications are suggested. 

1580 Table B-l - Suggested Feature Test Macros 

1681 . 


1582 

Symbol 

Description 

1583 

_V7 

Version 7 

1584 

_BSD 

General BSD systems 

1585 

_BSD4 2 

4.2BSD 

1586 

_BSD4 3 

4.3BSD 

1587 

_SYSIII 

System III 

1588 

_SYSV 

System V.l, V.2 

1589 

_SYSV3 

System V.3 

1590 

_XPGn 

X/Open Portability Guide, Issue n 

1591 

_USR_GROUP 

The 1984 /usr/group standard 


1592 - - 

1593 Only symbols that are actually in the porting base or industry specification should 

1594 be enabled by these symbols. 

1595 Feature test macros for implementation extensions will also probably be required. 

1596 Quite a few of these are traditionally available, but are in violation of the intent of 

1597 namespace pollution control. These can be made conforming simply by prefixing 

1598 them with an underscore. Symbols beginning with “_POSIX” are strongly 

1599 discouraged, as they will probably be used by later revisions of POSIX.l v 

1600 The environment for compilation has traditionally been fairly portable in histori- 
leoi cal systems, but during the transition to the C Standard {2} there will be confu- 

1602 sion about how to specify that a C Standard {2} compiler is expected, as considera- 

1603 tions of backwards compatibility will constrain many implementors from provid- 

1604 ing a conformant environment replacing the traditional one. This concern has 

1605 more to do with the issues of namespace than with the syntax of the language 

1606 accepted, which is highly compatible. 

1607 For systems that are sufficiently similar to traditional UNIX systems for this to | 

1608 make sense, it is suggested that if a compilation line of the form j 

1609 cc -d stdc ... | 

1610 is provided, that the system provide an environment that is conformant with the 

ion C Standard (2), at least with respect to namespace. | 

1612 It was decided to use feature test macros, rather than the inclusion of a header, 

1613 both because cunistd. h> was already in use and would itself have this problem, 

1614 and because the underlying mechanism would probably have been this anyway, 

1615 but in a less flexible fashion. 
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1616 POSIX. 1 requires that headers be included in all cases, although it is not directly 

1617 clear from the text at this point in the standard. If a function does not need any 

1618 special types, then it must be declared in cunistd. h>, as stated here. If it does 

1619 require something special, then it has an associated header, and the program will 

1620 not compile without that header. 

1621 B.2.7.3 Headers and Function Prototypes 

1622 The statement that names need not be carried forward literally exists for several | 

1623 reasons. These include the fact that some vendors may historically use other | 

1624 names and that the names are irrelevant to application portability. More impor- | 

1625 tantly, because of the pervasive nature of C macros, a declaration of the form: | 

1626 kill (pid_t pid, int sig) ; I 

1627 could be seriously undermined by a (perfectly valid) user declaration of the form: | 

1628 #define pid statusstruct .pidinfo 1 

1629 B.2.8 Numerical Limits 

1630 This subclause clarifies the scope and mutability of several classes of limits. | 

1631 B.2.8.1 C Language Limits 

1632 See also 2.7 and B.l. 1.1. 

1633 (CHAR_MIN) It is possible to tell if the implementation supports native char- 

1634 acter comparison as signed or unsigned by comparing this limit 

1635 to zero. 

1636 (WORD_BIT) This limit has been omitted, as it is not referenced elsewhere in 

1637 POSIX.1. 

1638 No limits are given in climits". h> for floating point values because none of the 

1639 functions in POSIX 1 use floating point values, and all the functions that do that 

1640 are imported from the C Standard {2} by 8.1, as are the limits that apply to the 

1641 floating point values associated with them. 

1642 Though limits to the addresses to system calls were proposed, they were not 

1643 included in POSIX.1 because it is not clear how to implement them for the range of 

1644 systems being considered, and no complete proposal was ever received. Limits | 

1645 regarding hardware register characteristics were similarly proposed and not 

1646 attempted. 

1647 B.2.8.2 Minimum Values 

1648 There has been confusion about the minimum maxima, and when that is under- 

1649 stood there is still a concern about providing ways to allocate storage based on the 

1650 symbols. This is particularly true for those in 2.8.4 where an indeterminate value 

1651 will leave the programmer with no symbol upon which to fall back. 

1652 Providing explicit symbols for the minima (from the implementor’s point of view, 

1653 or maxima from the the application’s point of view) helps to resolve possible 
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1654 confusion. Symbols are still provided for the actual value, and it is expected that 

1655 many applications will take advantage of these larger values, but they need not 

1656 do so unless it is to their advantage. Where the values in this subclause are ade- | 

1657 quate for the application, it should use them. These are given symbolically both | 

1658 because it is easier to understand and because the values of these symbols could 

1659 change between revisions of POSIX. 1 . Arguments to “good programming practice 
i860 also apply. 

1661 B.2.8.3 Run-Time Increasable Values 

1662 The heading of the far-right column of the table is given as “Minimum Value” 

1663 rather than “Value” in order to emphasize that the numbers given in that column 

1664 are minimal for the actual values a specific implementation is permitted to define 

1665 in its <limits.h>. The values in the actual <limits.h> define, in turn, the 

1666 maximum amount of a given resource that a Conforming POSIX.l Application can 

1667 depend on finding when translated to execute on that implementation. A Con- 

1668 forming POSIX. 1 Application Using Extensions must function correctly even if the 

1669 value given in <limits.h> is the minimum that is specified in POSIX.l. (The 

1670 application may still be written so that it performs more efficiently when a larger 

1671 value is found in <limits.h>.) A conforming implementation must provide at 

1672 least as much of a particular resource as that given by the value in POSIX.l. An 

1673 implementation that cannot meet this requirement (a “toy implementation”) can- 

1674 not be a conforming implementation. 

1675 B.2.8.4 Run-Time Invariant Values (Possibly Indeterminate) 

1676 (CHILD_MAX) This name can be misleading. This limit applies to all 

1677 processes in the system with the same user ID, regardless of 

1678 ancestry. 


1679 B.2.8.5 Pathname Variable Values 

1680 (MAXJNPUT) Since the only use of this limit is in relation to terminal input 

leal queues, it mentions them specifically. This limit was originally 

1682 named {MAX_CHAR}. Application writers should use 

1683 {MAX_INPUT} primarily as an indication of the number of bytes 

1684 that can be written as a single unit by one Conforming POSIX.l 

1685 Application Using Extensions communicating with another via 

1686 a terminal device. It is not implied that input lines received 

1687 from terminal devices always contain {MAX_INPUT} bytes or 

1688 fewer: an application that attempts to read more than 

1689 {MAX_INPUT} bytes from a terminal may receive more than 

1690 {MAXJNPUT} bytes. 

1691 It is not obvious that (MAXJNPUT) is of direct value to the 

1692 application writer. The existence of such a value (whatever it 

1693 may be) is directly of use in understanding how the tty driver 

1694 works (particularly with respect to flow control and dropped 

1695 characters). The value can be determined by finding out when 

1696 flow control takes effect (see the description of IXOFF in 

1697 7. 1.2.2). 
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1698 

1699 
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1707 
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1709 

1710 

1711 

1712 

1713 

1714 

1715 

1716 

1717 

1718 

1719 


Understanding that the limit exists and knowing its magnitude 
is important to making certain classes of applications work 
correctly. It is unlikely to be used in an application, but its 
presence makes POSIX. 1 clearer. 

(PATH_MAX) A Conforming POSIX. 1 Application or Conforming POSIX. 1 
Application Using Extensions that, for example, compiles to use 
different algorithms depending on the value of {PATH_MAX} 
should use code such as: 

#if defined (path_max) && path_max < 512 
#else x 

#if defined (patA_max) /* path_max >=* 512 */ 

#else /* path_max indeterminate */ 

#endif 

#endif 

This is because the value tends to be very large or indeter- 
minate on most historical implementations (it is arbitrarily 
large on System V). On such systems there is no way to quan- 
tify the limit, and it seems counterproductive to include an 
artificially small fixed value in <limit s . h> in such cases. 



1720 B.2.9 Symbolic Constants 

1721 B. 2.9.1 Symbolic Constants for the access () Function 

1722 There is no additional rationale provided for this subclause. 

1723 B.2.9.2 Symbolic Constants for the Iseek () Function 

1724 There is no additional rationale provided for this subclause. 

1725 B.2.9.3 Compile-Time Symbolic Constants for Portability Specifications 

1726 The purpose of this material is to allow an application developer to have a chance | 

1727 to determine whether a given application would run (or run well) on a given 

1728 implementation. To this purpose has been added that of simplifying development 

1729 of verification suites for POSIX.l. The constants given here were originally pro- | 

1730 posed for a separate file, <posix.h>, but it was decided that they should appear | 

1731 in cunistd . h> along with other symbolic constants. I 

1732 B.2.9.4 Execution-Time Symbolic Constants for Portability Specifications 

1733 Without the addition of (_POSIX_NO_TRUNC) and LPC_NO_TRUNC) to this list, 

1734 POSIX. 1 says nothing about the effect of a pathname component longer than 

1735 (NAME_MAX). There are only two effects in common use in implementations: 

1736 truncation or an error. It is desirable to limit allowable behavior to these two 
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1737 cases. It is also desirable to permit applications to determine what an 
i73« implementation’s behavior is because services that are available with one 

1739 behavior may be impractical to provide with the other. However, since the 

1740 behavior may vary from one file system to another, it may be necessary to use 

1741 pathconf { ) to resolve it. 


1742 B.3 Process Primitives 

1743 Consideration was given to enumerating all characteristics of a process defined by | 

1744 POSIX. 1 and describing each function in terms of its effects on those characteris- 
es tics, rather than English text. This is quite different from any known descriptions 

1746 of historical implementations, and it was not certain that this could be done ade- | 

1747 quately and completely enough to produce a usable standard. Providing such 

1748 descriptions in addition to the text was also considered. This was not done 

1749 because it would provide at best two redundant descriptions, and more likely two 

i7so descriptions with subtle inconsistencies. 

1751 B.3.1 Process Creation and Execution 

1752 Running a new program takes two steps. First the existing process (the parent) 

1763 calls the fork() function, producing a new process (the child), which is a copy of 

1754 itself. One of these processes (normally, but not necessarily, the child) then calls 

1755 one of the exec functions to overlay itself with a copy of the new process image. 

1756 If the new program is to be run synchronously (the parent suspends execution 

1757 until the child completes), the parent process then uses either the wait() or wait- 

1758 pid() function. If the new program is to be run asynchronously, it does not suffice 

1759 to simply omit the wait() or waitpidO call, because after the child terminates it 

1760 continues to hold some resources until it is waited for. A common way to produce 

1761 (“spawn”) a descendant process that does not need to be waited on is to fork() to 

1762 produce a child and wait() on the child. The child fork() s again to produce a 

1763 grandchild. The child then exits and the parent’s wait() returns. The grandchild 

1764 is thus disinherited by its grandparent. 

1765 A simpler method (from the programmer’s point of view) of spawning is to do 

1766 system("something &"); 

1767 However, this depends on features of a process (the shell) that are outside the 

1768 scope of POSIX. 1, although they are currently being addressed by the working | 

1769 group preparing ISO/IEC 9945-2 (B36). j 

1770 B.3. 1.1 Process Creation 

1771 Many historical implementations have timing windows where a signal sent to a | 

1772 process group (e.g., an interactive SIGINT) just prior to or during execution of 

1773 fork () is delivered to the parent following the fork () but not to the child because 

1774 the forkO code clears the child’s set of pending signals. POSIX.1 does not require, 
1776 or even permit, this behavior. However, it is pragmatic to expect that problems of 
1776 this nature may continue to exist in implementations that appear to conform to 
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1777 POSIX.1 and pass available verification suites. This behavior is only a conse- 

1778 quence of the implementation failing to make the interval between signal genera- 

1779 tion and delivery totally invisible. From the application’s perspective, a fork() call 

1780 should appear atomic. A signal that is generated prior to the fork () should be 

1781 delivered prior to the fork(). A signal sent to the process group after the forkO 

1782 should be delivered to both parent and child. The implementation might actually 

1783 initialize internal data structures corresponding to the child’s set of pending sig- 

1784 nals to include signals sent to the process group during the fork{). Since the 
1786 fork() call can be considered as atomic from the application’s perspective, the set 

1786 would be initialized as empty and such signals would have arrived after the 

1787 fork(). See also B.3. 3. 1.2. 

1788 One approach that has been suggested to address the problem of signal inheri- 

1789 tance across forki) is to add an [EINTR] error, which would be returned when a 

1790 signal is detected during the call. While this is preferable to losing signals, it was 

1791 not considered an optimal solution. Although it is not recommended for this pur- 

1792 pose, such an error would be an allowable extension for an implementation. 

'1793 The [ENOMEM] error value is reserved for those implementations that detect and 

1794 distinguish such a condition. This condition occurs when an implementation 

1795 detects that there is not enough memory to create the process. This is intended to 

1796 be returned when [EAGAIN] is inappropriate because there can never be enough 

1797 memory (either primary or secondary storage) to perform the operation. Because 

1798 fork () duplicates an existing process, this must be a condition where there is 

1799 sufficient memory for one such process, but not for two. Many historical imple- 

1 800 mentations actually return [ENOMEM] due to temporary lack of memory, a case 

1 801 that is not generally distinct from [EAGAIN] from the perspective of a portable 

1802 application. 

1803 Part of the reason for including the optional error [ENOMEM] is because the SV1D 

1804 [B39] specifies it and it should be reserved for the error condition specified there. 

1805 The condition is not applicable on many implementations. 

1806 IEEE Std 1003.1-1988 neglected to require concurrent execution of the parent and 

1807 child of fork(). A system that single-threads processes was clearly not intended 

1808 and is considered an unacceptable, “toy implementation” of POSIX.1. The only 

1809 objection anticipated to the phrase “executing independently” is testability, but 

1810 this assertion should be testable. Such tests require that both the parent and 

1811 child can block on a detectable action of the other, such as a write to a pipe or a 

18 1 2 signal. An interactive exchange of such actions should be possible for the system 

1813 to conform to the intent of POSIX.1. 

1814 The [EAGAIN] error exists to warn applications that such a condition might occur. 

1815 Whether it will occur or not is not in any practical sense under the control of the 

1816 application because the condition is usually a consequence of the user’s use of the 

1817 system, not of the application’s code. Thus, no application can or should rely upon 
1818 ' its occurrence under any circumstances, nor should the exact semantics of what 

1 819 concept of “user” is used be of concern to the application writer. Validation writ- 

1820 ers should be cognizant of this limitation. 
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1821 B.3.1.2 Execute a File 

1822 Early drafts of POSIX.1 required that the value of argc passed to maini) be “one or | 

1823 greater.” This was driven by the same requirement in drafts of the C Standard 

1824 (2). In fact, historical implementations have passed a value of zero when no argu- 
1826 ments are supplied to the caller of the exec functions. This requirement was 

1826 removed from the C Standard {2} and subsequently removed from POSIX.1 as well. 

1827 The POSIX.1 wording, in particular the use of the word “should,” requires a 

1828 Strictly Conforming POSIX.1 Application (see 1.3.3) to pass at least one argument 

1829 to the exec function, thus guaranteeing that argc be one or greater when invoked 

1830 by such an application. In fact, this is good practice, since many existing applica- 

1831 tions reference argu [0] without first checking the value of argc . 

1832 The requirement on a Strictly Conforming POSIX.1 Application also states that 

1833 the value passed as the first argument be a filename associated with the process 

1834 being started. Although some existing applications pass a pathname rather than 
1836 a filename in some circumstances, a filename is more generally useful, since the 

1836 common usage of argv[ 0] is in printing diagnostics. In some cases the filename 

1837 passed is not the actual filename of the file; for example, many implementations 

1838 of the login utility use a convention of prefixing a hyphen (-) to the actual 

1839 filename, which indicates to the command interpreter being invoked that it is a 

1840 “login shell.” 

1841 Some systems can exec shell scripts. This functionality is outside the scope of 

1842 POSIX.1, since it requires standardization of the command interpreter language of 

1843 the script and/or where to find a command interpreter. These fall in the domain 

1844 of the shell and utilities standard, currently under development as ISO/IEC 9945-2 | 

1845 (B36). However, it is important that POSIX.1 neither require nor preclude any | 

1846 reasonable implementation of this behavior. In particular, the description of the 

1847 [ENOEXEC 1 error is intended to permit discretion to implementations on whether 

1848 to give this error for shell scripts. 

1849 One common historical implementation is that the execli), execv (), execle (), and | 

i 860 execve () functions return an [ENOEXEC] error for any file not recognizable as exe- 

1851 cutable, including a shell script. When the execlpi) and execvpi) functions 

1852 encounter such a file, they assume the file to be a shell script and invoke a known 

1853 command interpreter to interpret such files. These implementations of execvpO 

1864 and execlpi) only give the [ENOEXEC] error in the rare case of a problem with the 

1855 command interpreter’s executable file. Because of these implementations the 

1856 [ENOEXEC] error is not mentioned for execlpi ) or execvpi), although implementa- 

1857 tions can still give it. 

1858 Another way that some historical implementations handle shell scripts is by | 

1859 recognizing the first two bytes of the file as the character string # ! and using the | 

1 860 remainder of the first line of the file as the name of the command interpreter to 

1861 execute. 

1862 Some implementations provide a third argument to maini) called envp. This is 

1863 defined as a pointer to the environment. The C Standard (2} specifies invoking 

1864 maini) with two arguments, so implementations must support applications writ- 

1865 ten this way. Since POSIX.1 defines the global variable environ , which is also pro- 

1866 vided by historical implementations and can be used anywhere envp could be | 

1867 used, there is no functional need for the envp argument. Applications should use 
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1868 the getenvi) function rather than accessing the environment directly via either 

1869 envp or environ . Implementations are required to support the two-argument cal- 

1870 ling sequence, but this does not prohibit an implementation from supporting envp 

1871 as an optional, third argument. 

1872 POSIX.1 specifies that signals set to SIG_IGN remain set to SIG_IGN and that the 

1873 process signal mask be unchanged across an exec. This is consistent with histori- 

1874 cal implementations, and it permits some useful functionality, such as the nohup 

1875 command. However, it should be noted that many existing applications wrongly 

1876 assume that they start with certain signals set to the default action and/or 

1877 unblocked. In particular, applications written with a simpler signal model that 

1878 does not include blocking of signals, such as the one in the C Standard (2), may 

1879 not behave properly if invoked with some signals blocked. Therefore, it is best not 
i 860 to block or ignore signals across exec s without explicit reason to do so, and espe- 

1881 dally not to block signals across execs of arbitrary (not closely co-operating) 

1882 programs. 

1883 If [_POSIX_SAVED_IDS] is defined, the exec functions always save the value of the 

1884 effective user ID and effective group ID of the process at the completion of the 

1885 exec, whether or not the set-user-ID or the set-group-ID bit of the process image 

1886 file is set. 

1887 The statement about argv[] and envp[ ] being constants is included to make expli- 

1888 cit to future writers of language bindings that these objects are completely con- 

1889 stant. Due to a limitation of the C Standard [2], it is not possible to state that 

1890 idea in Standard C. Spedfying two levels of const-qualification for the argv[ ] 

1891 and envp[ ] parameters for the exec functions may seem to be the natural choice, 

1892 given that these functions do not modify either the array of pointers or the charac- 

1893 ters to which the function points, but this would disallow existing correct code. 

1894 Instead, only the array of pointers is noted as constant. The table of assignment 

1896 compatibility for dst = src, derived from the C Standard (2), summarizes the 

1896 compatibility: 

1897 

1898 

1899 

1900 

1901 

1902 

1903 

1904 

1905 Since all existing code has a source type matching the first row, the column that 

1906 gives the most valid combinations is the third column. The only other possibility 

1907 is the fourth column, but using it would require a cast on the argv or envp argu- 

1908 ments. It is unfortunate that the fourth column cannot be used, because the 

1909 declaration a nonexpert would naturally use would be that in the second row. 

1910 The C Standard (2} and POSIX1 do not conflict on the use of environ, but some 

1911 historical implementations of environ may cause a conflict. As long as environ is 

1912 treated in the same way as an entry point (e.g., forki )], it conforms to both stan- 

1913 dards. A library can contain forki), but if there is a user-provided forki), that 
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forki) is given precedence and no problem ensues. The situation is similar for | 
environ— the POSIX.l definition is to be used if there is no user-provided environ | 
to take precedence. At least three implementations are known to exist that solve | 
this problem. 

[E 2 BIG] The limit [ARG_MAX] applies not just to the size of the argu- 

ment list, but to the sum of that and the size of the environ- 
ment list. 

[EFAULT] Some historical systems return [EFAULT] rather than | 
[ENOEXEC] when the new process image file is corrupted. They 
are nonconforming. 

[ENAMETOOLONG] 

Since the file pathname may be constructed by taking elements 
in the PATH variable and putting them together with the 
filename, the [ENAMETOOLONG] condition could also be 
reached this way. 

[ETXTBSY] The error [ETXTBSY] was considered too implementation 
dependent to include. System V returns this error when the 
executable file is currently open for writing by some process. 
POSIX.l neither requires nor prohibits this behavior. 

Other systems (such as System V) may return [EINTR] from exec . This is not 
addressed by POSIX.l, but implementations may have a window between the call 
to exec and the time that a signal could cause one of the exec calls to return with 
[EINTR]. 


1937 B.3.2 Process Termination 

1938 Early drafts drew a different distinction between normal and abnormal process | 

1939 termination. Abnormal termination was caused only by certain signals and 

1940 resulted in implementation-defined “actions,” as discussed below. Subsequent 

1941 drafts of POSIX.l distinguished three types of termination: normal termination 

1942 (as in the current POSIX. 1 ), “simple abnormal termination,” and “abnormal termi- 

1943 nation with actions.” Again the distinction between the two types of abnormal 

1944 termination was that they were caused by different signals and that 

1945 implementation-defined actions would result in the latter case. Given that these 

1946 actions were completely implementation defined, the early drafts were only saying 

1947 when the actions could occur and how their occurrence could be detected, but not 

1948 what they were. This was of little or no use to portable applications, and thus the 

1949 distinction was dropped from POSIX. 1 . 

i960 The implementation-defined actions usually include, in most historical implemen- 
ts l tations, the creation of a file named core in the current working directory of the 

1952 process. This file contains an image of the memory of the process, together with 

1953 descriptive information about the process, perhaps sufficient to reconstruct the 

1954 state of the process at the receipt of the signal. 

1955 There is a potential security problem in creating a core file if the process was 
1966 set-user-ID and the current user is not the owner of the program, if the process 
1957 was set-group-ID and none of the user’s groups match the group of the program, 
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1958 or if the user does not have permission to write in the current directory. In this 

1959 situation, an implementation either should not create a core file or should make 

1 960 it unreadable by the user. 

1961 Despite the silence of POSIX.l on this feature, applications are advised not to 

1962 create files named core because of potential conflicts in many implementations. 

1963 Some historical implementations use a different name than core for the file, such 

1964 as by appending the process ID to the filename. 

1965 B.3.2. 1 Wait for Process Termination 

1966 A call to the wait( ) or waitpidO function only returns status on an immediate 

1967 child process of the calling process; i.e., a child that was produced by a single 

1968 fork () call (perhaps followed by an exec or other function calls) from the parent. If 

1969 a child produces grandchildren by further use of forki), none of those grandchil- 

1970 dren nor any of their descendants will affect the behavior of a waiti) from the ori- 

1971 ginal parent process. Nothing in POSIX .1 prevents an implementation from pro- 

1972 viding extensions that permit a process to get status from a grandchild or any 

1973 other process, but a process that does not use such extensions must be guaranteed 

1974 to see status from only its direct children. 

1975 The waitpidO function is provided for three reasons: 

1976 — To support job control (see B. 3 . 3 ). 

1977 — To permit a nonblocking version of the waiti,) function. 

1978 — To permit a library routine, such as systemi) or pclose (), to wait for its chil- 

1979 dren without interfering with other terminated children for which the pro- 

1980 cess has not waited. 
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The first two of these facilities are based on the wait3() function provided by 
4 . 3 BSD. The interface uses the options argument, which is identical to an argu- 
ment to wait3 {). The WUNTRACED flag is used only in conjunction with job con- 
trol on systems supporting that option. Its name comes from 4 . 3 BSD and refers to 
the fact that there are two types of stopped processes in that implementation. 


processes being traced via the ptraceO debugging facility and (un traced) processes 
stopped by job-control signals. Since ptraceO is not part of POSIX.l, only the 
second type is relevant. The name WUNTRACED was retained because its usage | 
is the same, even though the name is not intuitively meaningful in this context. 

The third reason for the waitpidO function is to permit independent sections of a 
process to spawn and wait for children without interfering with each other. I< or 
example, the following problem occurs in developing a portable shell, or command | 
interpreter: ^ 

stream = popen ("/bin/true") ; 

(void) system ("sleep 100") ; 

(void) pclose (stream) ; 

On all historical implementations, the final pclose () will fail to reap the wait 
status of the popenO- 

The status values are retrieved by macros, rather than given as specific bit encod- 
ings as they are in most historical implementations (and thus expected by 
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2001 existing programs). This was necessary to eliminate a limitation on the number 

2002 of signals an implementation can support that was inherent in the traditional 

2003 encodings. POSIX.l does require that a status value of zero corresponds to a pro- 

2004 cess calling _exit(.0), as this is the most common encoding expected by existing 

2005 programs. Some of the macro names wore adopted from 4.3BSD. 

2006 These macros syntactically operate on an arbitrary integer value. The behavior is 

2007 undefined unless that value is ono stored by a successful call to wait 0 or wait- 
2oos pid() in the location pointed to by the statjoc argument. An earlier draft 

2009 attempted to make this clearer by specifying each argument as *statJoc rather 

2010 than statjial . However, that did not follow the conventions of other specifications 

2011 in POSIX. 1 or traditional usage. It also could have implied that the argument to 

2012 the macro must literally be *stat_loc', in fact, that value can be stored or passed as 

2013 an argument to other functions before being interpreted by these macros. 

2014 The extension that affects waitO and waitpidO and is common in historical imple- 

2015 mentations is the ptrace () function. It is called by a child process and causes that 

2016 child to stop and return a status that appears identical to the status indicated by 

2017 WIFSTOPPED. The status of ptraced children is traditionally returned regardless 

2018 of the WUNTRACED flag for by the waitO function]. Most applications do not need 

2019 to concern themselves with such extensions because they have control over what 

2020 extensions they or their children use. However, applications, such as command 

2021 interpreters, that invoke arbitrary processes may see this behavior when those 

2022 arbitrary processes misuse such extensions. 

2023 Implementations that support core file creation or other implementation-defined 

2024 actions on termination of some processes traditionally provide a bit in the status 

2025 returned by waiti ) to indicate that such actions have occurred. 

2026 B.3.2.2 Terminate a Process 

2027 Most C language programs should use the exit () function rather than exit ( ). The 

2028 _exit() function is defined here instead of exit 0 because the C Standard ( 2 ) defines 

2029 the latter to have certain characteristics that are beyond the scope of POSIX.l, 

2030 specifically the flushing of buffers on open files and the use of atexiti). See The C | 

2031 Language” in the Introduction. There are several public-domain implementations | 

2032 of atexitO that may be of use to interface implementors who wish to incorporate it. 

2033 It is important that the consequences of process termination as described in this 

2034 subclause occur regardless of whether the process called _exit{) [perhaps | 

2035 indirectly through exitO] or instead was terminated due to a signal or for some 

2036 other reason. Note that in the specific case of exit 0 this means that the status 

2037 argument to exit () is treated the same as the status argument to _exit() . See also 

2038 B. 3 . 2 . 

2039 A language other than C may have other termination primitives than the C 

2040 language exitO function, and programs written in such a language should use its 

2041 native termination primitives, but those should have as part of their function the 

2042 behavior of _exitO as described in this subclause. Implementations in languages | 

2043 other than C are outside the scope of the present version of POSIX.1, however. 

2044 As required by the C Standard ( 2 ), using return from mainO is equivalent to cal- | 

2045 ling exitO with the same argument value. Also, reaching the end of the maini ) 
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function is equivalent to using exitO with an unspecified value. 

A value of zero (or EXIT_SUCCESS, which is required by 8.1 to be zero) for the 
argument status conventionally indicates successful termination. This 
corresponds to the specification for exiti ) in the C Standard (2). The convention is 
followed by utilities such as make and various shells, which interpret a zero 
status from a child process as success. For this reason, applications should not 
call exiti 0) or ^exit(O) when they terminate unsuccessfully, for example in signal- 
catching functions. 

Historically, the implementation-dependent process that inherits children whose 
parents have terminated without waiting on them is called init and has a pro- 
cess ID of 1. \ 

The sending of a SIGHUP to the foreground process group when a controlling pro- 
cess terminates corresponds to somewhat different historical implementations. In 
System V, the kernel sends a SIGHUP on termination of (essentially) a controlling 
process. In 4.2BSD, the kernel does not send SIGHUP in a case like this, but the 
termination of a controlling process is usually noticed by a system daemon, which 
arranges to send a SIGHUP to the foreground process group with the vhangupO 
function. However, in 4.2BSD, due to the behavior of the shells that support job 
control, the controlling process is usually a shell with no other processes in its 
process group. Thus, a change to make jixitO behave this way in such systems 
should not cause problems with existing applications. 

The termination of a process may cause a process group to become orphaned in 
either of two ways. The connection of a process group to its parent(s) outside of 
the group depends on both the parents and their children. Thus, a process group 
may be orphaned by the termination of the last connecting parent process outside 
of the group or by the termination of the last direct descendant of the parent 
process(es). In either case, if the termination of a process causes a process ptmp 
to become orphaned, processes within the group are disconnected from their job 
control shell, which no longer has any information on the existence of the process 
group. Stopped processes within the group would languish forever. In order to 
avoid this problem, newly orphaned process groups that contain stopped processes 
are sent a SIGHUP signal and a SIGCONT signal to indicate that they have been 
disconnected from their session. The SIGHUP signal causes the process group 
members to terminate unless they are catching or ignoring SIGHUP . Under most 
circumstances, all of the members of the process group are stopped if any of them 
are stopped. 

The action of sending a SIGHUP and a SIGCONT signal to members of a newly 
orphaned process group is similar to the action of 4.2BSD, which sends SIGHUP 
and SIGCONT to each stopped child of an exiting process. If such children exit in 
response to the SIGHUP, any additional descendants will receive similar treat- 
ment at that time. In POSIX.l, the signals will be sent to the entire process group 
at the same time. Also, in POSIX.l, but not in 4.2BSD, stopped processes may be 
orphaned, but may be members of a process group that is not orphaned; therefore, 
the action taken at _exitO must consider processes other than child processes. 

It is possible for a process group to be orphaned by a call to setpgid 0 or setsidO, 
as well as by process termination. POSIX 1 does not require sending SIGHUP and 
SIGCONT in those cases, because, unlike process termination, those cases will not 
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2093 be caused accidentally by applications that are unaware of job control. An imple- | 

2094 mentation can choose to send SIGHUP and SIGCONT in those cases as an exten- | 

2095 sion; such an extension must be documented as required in 3.3. 1.2. | 

2096 B.3.3 Signals 

2097 Signals, as defined in Version 7, System III, the 1984 /usr/ group Standard (B59), | 

2098 and System V (except very recent releases), have shortcomings that make them j 

2099 unreliable for many application uses. Several objections were raised against early j 

2100 drafts of P0SIX.1 because of this. Therefore, a new signal mechanism, based very j 

2101 closely on the one of 4.2BSD and 4.3BSD, was added to POSIX.1. With the excep- 

2102 tion of one feature (see item (4) below and also sigpendingO J, it is possible to 

2103 implement the P0SIX.1 interface as a simple library veneer on top of 4.3BSD. 

2104 There are also a few minor aspects of the underlying 4.3BSD implementation (as 
2 ior> opposed to the interface) that would also need to change to conform to POSIX. 1. 

2106 The mqjor differences from the BSD mechanism are: 

2107 

2108 

2109 

2110 
2111 
2112 

2113 (2) Restarting system calls. Unlike all previous historical implementations, 

2114 4.2BSD restarts some interrupted system calls rather than returning an 

2i is error with errno set to [EINTRj after the signal-catching function returns. 

2116 This change caused problems for some existing application code. 4.3BSD 

2H7 and other systems derived from 4.2BSD allow the application to choose 

2H8 whether system calls are to be restarted. POSIX.1 (in 3.3.4) does not 

2H9 require restart of functions because it was not clear that the semantics of 

2120 system-call restart in any historical implementation were useful enough | 

2121 to be of value in a standard. Implementors are free to add such mechan- 

2122 isms as extensions. 

2123 (3) Signal stacks. The 4.2BSD mechanism includes a function sigstack (). 

2124 The 4.3BSD mechanism includes this and a function sigreturn(). No 

2125 equivalent is included in POSIX.1 because these functions are not port- 

2126 able, and no sufficiently portable and useful equivalent has been 

2127 identified. See also 8.3.1. 

2128 (4) Pending signals. The sigpending () function is the sole new signal opera- | 

2129 tion introduced in POSIX.1. | 

2130 A proposal was considered for making reliable signals optional. However, the | 

2131 consensus was that this would hurt application portability, as a large percentage 

2132 of applications using signals can be hurt by the unreliable aspects of historical 

2133 implementations of the signals ) mechanism defined by the C Standard (2). This 

2134 unreliability stems from the fact that the signal action is reset to SIG_DFL before 

2135 the user’s signal-catching routine is entered. The C Standard (2) does not require 

2136 this behavior, but does explicitly permit it, and most historical implementations | 

2137 behave this way. 


(1) Signal mask type. BSD uses the type int to represent a signal mask, thus 
limiting the number of signals to the number of bits in an int (typically 
32). The new standard instead uses a defined type for signal masks. 
Because of this change, the interface is significantly different than it is in 
BSD implementations, although the functionality, and potentially the 
implementation, are very similar. 
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For example, an application that catches the SIGINT signal using signalO could 
be terminated with no chance to recover when two such signals arrive sufficiently 
close in time (e.g., when an impatient user types the INTR character twice in a 
row on a busy system). Although the C Standard (2} no longer requires this 
unreliable behavior, many historical implementations, including System V, will 
reset the signal action to SIG_DFL. For this reason, it is strongly recommended 
that the signalO function not be used by POSIX.1 conforming applications. Imple- 
mentations should also consider blocking signals during the execution of the 
signal -catching function instead of resetting the action to SIG_DFL, but backward 
compatibility considerations will most likely prevent this from becoming 
universal. 

Most historical implementations do hot queue signals; i.e., a process’s signal 
handler is invoked once, even if the signal has been generated multiple times 
before it is delivered. A notable exception to this is SIGCLD, which, in System V, 
is queued. The queueing of signals is neither required nor prohibited by POSIX.1. 
See 3.3. 1.2. It is expected that a future realtime extension to POSIX.1 will address 
the issue of reliable queueing of event notification. 


2156 B.3.3.1 Signal Concepts 

2156 B.3.3. 1.1 Signal Names 

2157 The restriction on the actual type used for sigsetj is intended to guarantee that 

2158 these objects can always be assigned, have their address taken, and be passed as 

2159 parameters by value. It is not intended that this type be a structure including 

2160 pointers to other data structures, as that could impact the portability of applica- 

2161 tions performing such operations. A reasonable implementation could be a struc- 

2162 ture containing an array of some integer type. 

2163 The signals described in POSIX.1 must have unique values so that they may be 

2164 named as parameters of case statements in the body of a C language switch 

2165 clause. However, implementation-defined signals may have values that overlap 

2166 with each other or with signals specified in this document. An example of this is 

2167 SIGABRT, which traditionally overlaps some other signal, such as SIGIOT. 

2168 SIGKILL, SIGTERM, SIGUSR1, and SIGUSR2 are ordinarily generated only through 

2169 the explicit use of the kill{) function, although some implementations generate 

2170 SIGKILL under extraordinary circumstances. SIGTERM is traditionally the 

2171 default signal sent by the kill command. 

2172 The signals SIGBUS, SIGEMT, SIGIOT, SIGTRAP, and SIGSYS were omitted from 

2173 POSIX.1 because their behavior is implementation dependent and could not be 

2174 adequately categorized. Conforming implementations may deliver these signals, 
2176 but must document the circumstances under which they are delivered and note 

2176 any restrictions concerning their delivery. The signals SIGFPE, SIGILL, and SIG- 

2177 SEGV are similar in that they also generally result only from programming errors. 

2178 They were included in POSIX.1 because they do indicate three relatively well- 

2179 categorized conditions. They are all defined by the C Standard (2) and thus would 

2180 have to be defined by any system with a C Standard (2} binding, even if not expli- 

2181 citly included in POSIX.1. 
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2182 There is very little that a Conforming POSIX.l Application can do by catching, 

2183 ignoring, or masking any of the signals SIGILL, SIGTRAP, SIGIOT, SIGEMT, 

2184 SIGBUS, SIGSEGV, SIGSYS, or SIGFPE. They will generally be generated by the 
2186 system only in cases of programming errors. While it may be desirable for some 

2186 robust code (e.g., a library routine) to be able to detect and recover from program- 

2187 ming errors in other code, these signals are not nearly sufficient for that purpose. 

2188 One portable use that does exist for these signals is that a command interpreter 

2189 can recognize them as the cause of a process’s termination [with wait{ )] and print 

2190 an appropriate message. The mnemonic tags for these signals are derived from 

2191 their PDP-11 origin. 

2192 The signals SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, and SIGCONT are provided for 

2193 job control and are unchanged from 4.2BSD. The signal SIGCHLD is also typically 

2194 used by job control shells to detect children that have terminated or, as in 4.2BSD, 

2196 stopped. See also B.3.3.4. 

2196 Some implementations, including System V, have a signal named SIGCLD, which 

2197 is similar to SIGCHLD in 4.2BSD. POSIX.l permits implementations to have a sin- 

2198 gle signal with both names. POSIX.1 carefully specifies ways in which portable 

2199 applications can avoid the semantic differences between the two different imple- 

2200 mentations. The name SIGCHLD was chosen for POSIX.l because most current 

2201 application usages of it can remain unchanged in conforming applications. 

2202 SIGCLD in System V has more cases of semantics that POSIX.l does not specify, 

2203 and thus applications using it are more likely to require changes in addition to 

2204 the name change. 

2206 Some implementations that do not support job control may nonetheless imple- 

2206 ment SIGCHLD. Similarly, such an implementation may choose to implement SIG- 

2207 STOP. Since POSIX.l requires that symbolic names always be defined (with the 

2208 exception of certain names in <limit s . h> and <unistd . h>), a portable method 

2209 of determining, at run-time, whether an optional signal is supported is to call the 

2210 sigaction() function with NULL act and oact arguments. A successful return indi- 

2211 cates that the signal is supported. Note that if sysconf() shows that job control is 

2212 present, then all of the optional signals shall also be supported. 

2213 The signals SIGUSR1 and SIGUSR2 are commonly used by applications for 

2214 notification of exceptional behavior and are described as “reserved as application 

2215 defined” so that such use is not prohibited. Implementations should not generate 

2216 SIGUSR1 or SIGUSR2, except when explicitly requested by kill{). It is recom- 

2217 mended that libraries not use these two signals, as such use in libraries could 

2218 interfere with their use by applications calling the libraries. If such use is una- 

2219 voidable, it should be documented. It is prudent for nonportable libraries to use 

2220 nonstandard signals to avoid conflicts with use of standard signals by portable 

2221 libraries. 

2222 There is no portable way for an application to catch or ignore nonstandard sig- | 

2223 nals. Some implementations define the range of signal numbers, so applications 

2224 can install signal-catching functions for all of them. Unfortunately, 
2226 implementation-defined signals often cause problems when caught or ignored by 

2226 applications that do not understand the reason for the signal. While the desire 

2227 exists for an application to be more robust by handling all possible signals [even 

2228 those only generated by kill()] t no existing mechanism was found to be sufficiently 

2229 portable to include in POSIX.1. The value of such a mechanism, if included, would 
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2230 be diminished given that SIGKILL would still not be catchable. 

2231 B.3.3.1.2 Signal Generation and Delivery 

2232 The terras defined in this subclause are not used consistently in documentation of | 

2233 historical systems. Each signal can be considered to have a lifetime beginning | 

2234 with generation and ending with delivery. The POSIX.1 definition of delivery does | 

2236 not exclude ignored signals; this is considered a more consistent definition. | 

2236 Implementations should deliver unblocked signals as soon after they are gen- 

2237 erated as possible. However, it is difficult for POSIX.l to make specific require- 

2238 ments about this, beyond those in killQ and sigprocmaski). Even on systems with 

2239 prompt delivery, scheduling of higher priority processes is always likely to cause 

2240 delays. 

2241 In general, the interval between the generation and delivery of unblocked signals 

2242 cannot be detected by an application. Thus, references to pending signals gen- 

2243 erally apply to blocked, pending signals. 

2244 In the 4.3BSD system, signals that are blocked and set to SIG_IGN are discarded 
2246 immediately upon generation. For a signal that is ignored as its default action, if 

2246 the action is SIG_DFL and the signal is blocked, a generated signal remains pend- 

2247 ing. In the 4.1BSD system and in System V Release 3, two other implementations 

2248 that support a somewhat similar signal mechanism, all ignored, blocked signals 

2249 remain pending if generated. Because it is not normally useful for an application 

2260 to simultaneously ignore and block the same signal, it was unnecessary for 

2261 POSIX.1 to specify behavior that would invalidate any of the historical | 

2252 implementations. I 

2263 There is one case in some historical implementations where an unblocked, pend- | 

2264 ing signal does not remain pending until it is delivered. In the System V imple- 
2266 mentation of signalO, pending signals are discarded when the action is set to 

2266 SIG_DFL or a signal-catching routine (as well as to SIG_IGN). Except in the case 

2267 of setting SIGCHLD to SIG_DFL, implementations that do this do not conform com- 

2268 pletely to POSIX.1. Some earlier drafts of POSIX.l explicitly stated this, but these 
2259 statements were redundant due to the requirement that functions defined by 

1 2260 POSIX.1 not change attributes of processes defined by POSIX.1 except as explicitly 

2261 stated (see Section 3). 

2262 POSIX.1 specifically states that the order in which multiple, simultaneously pend- 

2263 ing signals are delivered is unspecified. This order has not been explicitly 

2264 specified in historical implementations, but has remained quite consistent and 

2265 been known to those familiar with the implementations. Thus, there have been 

2266 cases where applications (usually system utilities) have been written with explicit 

2267 or implicit dependencies on this order. Implementors and others porting existing 

2268 applications may need to be aware of such dependencies. 

2269 When there are multiple pending signals that are not blocked, implementations 

2270 should arrange for the delivery of all signals at once, if possible. Some implemen- 

2271 tations stack calls to all pending signal-catching routines, making it appear that 

2272 each signal-catcher was interrupted by the next signal. In this case, the imple- 

2273 mentation should ensure that this stacking of signals does not violate the seman- 

2274 tics of the signal masks established by sigaction{). Other implementations pro- 
2276 cess at most one signal when the operating system is entered, with remaining 
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2276 signals saved for later delivery. Although this practice is widespread, this | 

2277 behavior is neither standardized nor endorsed. In either case, implementations j 

2278 should attempt to deliver signals associated with the current state of the process 

2279 (e.g., SIGFPE) before other signals, if possible. 

2280 In 4.2BSD and 4.3BSD, it is not permissible to ignore or explicitly block SIGCONT 

2281 because if blocking or ignoring this signal prevented it from continuing a stopped 

2282 process, such a process could never be continued (only killed by SIGKILL). How- 

2283 ever, 4.2BSD and 4.3BSD do block SIGCONT during execution of its signal-catching 

2284 function when it is caught, creating exactly this problem. A proposal was con- | 

2285 sidered to disallow catching SIGCONT in addition to ignoring and blocking it, but j 

2286 this limitation led to objections. The consensus was to require that SIGCONT 

2287 always continue a stopped process when generated. This removed the need to 

2288 disallow ignoring or explicit blocking of the signal; note that SIG_IGN and 

2289 SIG_DFL are equivalent for SIGCONT. 

2290 B.3.3.1.3 Signal Actions 

2291 Earlier drafts of POSIX. 1 mentioned SIGCONT as a second exception to the rule 

2292 that signals are not delivered to stopped processes until continued. Because 

2293 POSIX. 1 now specifies that SIGCONT causes the stopped process to continue when 

2294 it is generated, delivery of SIGCONT is not prevented because a process is stopped, 

2295 even without an explicit exception to this rule. 

2296 Ignoring a signal by setting the action to SIG_IGN (or SIG_DFL for signals whose 

2297 default action is to ignore) is not the same as installing a signal-catching function 

2298 that simply returns. Invoking such a function will interrupt certain system func- 

2299 tions that block processes [e.g., wait(), sigsuspendO, pause(), read(), write ()] 

1 2300 while ignoring a signal has no such effect on the process. 

2301 Historical implementations discard pending signals when the action is set to 

2302 SIG_IGN. However, they do not always do the same when the action is set to 

2303 SIG_DFL and the default action is to ignore the signal. POSIX.l requires this for 

2304 the sake of consistency and also for completeness, since the only signal this 
2306 applies to is SIGCHLD, and POSIX.1 disallows setting its action to SIG_IGN. 

2306 The specification of the effects of SIG_IGN on SIGCHLD as implementation defined 

2307 permits, but does not require, the System V effect of causing terminating children 

2308 to be ignored by wait(). Yet it permits SIGCHLD to be effectively ignored in an 

2309 implementation-independent manner by use of SIG_DFL. 

2310 Some implementations (System V, for example) assign different semantics for 

2311 SIGCLD depending on whether the action is set to SIGJGN or SIG_DFL. Since 

2312 POSIX.1 requires that the default action for SIGCHLD be to ignore the signal, 

2313 applications should always set the action to SIGJDFL in order to avoid SIGCHLD. 

2314 Some implementations (System V, for example) will deliver a SIGCLD signal 

2315 immediately when a process establishes a signal-catching function for SIGCLD 

2316 when that process has a child that has already terminated. Other implementa- 

2317 tions, such as 4.3BSD, do not generate a new SIGCHLD signal in this way. In gen- 

2318 eral, a process should not attempt to alter the signal action for the SIGCHLD sig- 

2319 nal while it has any outstanding children. However, it is not always possible for a 

2320 process to avoid this; for example, shells sometimes start up processes in pipe- 

2321 lines with other processes from the pipeline as children. Processes that cannot 
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2322 ensure that they have no children when altering the signal action for SIGCHLD 

2323 thus need to be prepared for, but not depend on, generation of an immediate 

2324 SIGCHLD signal. 

2325 The default action of the stop signals (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is 

2326 to stop a process that is executing. If a stop signal is delivered to a process that is 

2327 already stopped, it has no effect. In fact, if a stop signal is generated for a 

2328 stopped process whose signal mask blocks the signal, the signal will never be 

2329 delivered to the process since the process must receive a SIGCONT, which discards 

2330 all pending stop signals, in order to continue executing. 

2331 The SIGCONT signal shall continue a stopped process even if SIGCONT is blocked 

2332 (or ignored). However, if a signal-catching routine has been established for 

2333 SIGCONT, it will not be entered until SIGCONT is unblocked. 

2334 If a process in an orphaned process group stops, it is no longer under the control 
2336 of a job-control shell and hence would not normally ever be continued. Because of 

2336 this, orphaned processes that receive terminal-related stop signals (SIGTSTP, 

2337 SIGTTIN, SIGTTOU, but not SIGSTOP) must not be allowed to stop. The goal i9 to 

2338 prevent stopped processes from languishing forever. [As SIGSTOP is sent only via 

2339 kill (), it is assumed that the process or user sending a SIGSTOP can send a 

2340 SIGCONT when desired.) Instead, the system must discard the stop signal. As an 

2341 extension, it may also deliver another signal in its place. 4.3BSD sends a SIG- 

2342 KILL, which is overly effective because SIGKILL is not catchable. Another possible 

2343 choice is SIGHUP. 4.3BSD also does this for orphaned processes (processes whose 

2344 parent has terminated) rather than for members of orphaned process groups; this 

2345 is less desirable because job-control shells manage process groups. POSIX.l also 

2346 prevents SIGTTIN and SIGTTOU signals from being generated for processes in 

2347 orphaned process groups as a direct result of activity on a terminal, preventing 

2348 infinite loops when read() and write () calls generate signals that are discarded. 

2349 (See B.7. 1.1.4.) A similar restriction on the generation of SIGTSTP was con- | 

2350 sidered, but that would be unnecessary and more difficult to implement due to its 

2351 asynchronous nature. 

2362 Although POSIX.1 requires that signal-catching functions be called with only one 

2353 argument, there is nothing to prevent conforming implementations from extend- 

2354 ing POSIX.1 to pass additional arguments, as long as Strictly Conforming POSIX.1 

2355 Applications continue to compile and execute correctly. Most historical implemen- 

2356 tations do, in fact, pass additional, signal-specific arguments to certain signal- 

2357 catching routines. 

2368 There was a proposal to change the declared type of the signal handler to: 

2369 void func (int sig, ... ) ; 

2360 The usage of ellipses (“, ... ") is C Standard (2) syntax to indicate a variable 

2361 number of arguments. Its use was intended to allow the implementation to pass 

2362 additional information to the signal handler in a standard manner. 

2363 Unfortunately, this construct would require all signal handlers to be defined with 

2364 this syntax because the C Standard (2} allows implementations to use a different 

2365 parameter passing mechanism for variable parameter lists than for nonvariable 

2366 parameter lists. Thus, all existing signal handlers in all existing applications 

2367 would have to be changed to use the variable syntax in order to be standard and 
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2.16« portable. This is in conflict with the goal of Minimal Changes to Existing Applica- 
2369 tion Code. 

2170 When terminating a process from a signal -catching function, processes should be 

2371 aware of any interpretation that their parent may make of the status returned by 

2372 waito or waitpidO. In particular, a signal-catching function should not call 

2373 exit(Q) or _exit( 0) unless it wants to indicate successful termination. A nonzero 

2374 argument to exitO or _cxitO can be used to indicate unsuccessful termination. 

2375 Alternatively, the process can use killO to 9end itself a fatal signal (first ensuring 

2376 that the signal is set to the default action and not blocked). (See also B.3.2.2). 

2377 The behavior of unsafe functions, as defined by this subclause, is undefined when | 

2378 they are invoked from signal-catching functions in certain circumstances. The | 

2379 behavior of reentrant functions, as defined by this subclause, is as specified by | 

2380 POSIX. 1, regardless of invocation from a signal-catching function. This is the only 

2381 intended meaning of the statement that reentrant functions may be used in 

2382 signal-catching functions without restriction. Applications must still consider all 

2383 effects of such functions on such things as data structures, files, and process state. 

2384 In particular, application writers need to consider the restrictions on interactions 

2385 when interrupting sleepO [see sleepO and B. 3.4. 31 and interactions among multi- 

2386 pie handles for a file description (see 8.2.3 and B.8.2.3). The fact that any specific 

2387 function is listed as reentrant does not necessarily mean that invocation of that 

2388 function from a signal-catching function is recommended. 

2389 In order to prevent errors arising from interrupting nonreentrant function calls, 

2390 applications should protect calls to these functions either by blocking the 

2391 appropriate signals or through the use of some programmatic semaphore. 

2392 POSIX. 1 does not address the more general problem of synchronizing access to 

2393 shared data structures. Note in particular that even the “safe” functions may 

2394 modify the global variable errno ; the signal-catching function may want to save 

2395 and restore its value. The same principles apply to the reentrancy of application 

2396 routines and asynchronous data access. 

2397 Note that longjmpO and siglongjmpO are not in the list of reentrant functions. 

2398 This is because the code executing after longjmpO or siglongjmpO can call any 

2399 unsafe functions with the same danger as calling those unsafe functions directly 

2400 from the signal handler. Applications that use longjmpO or siglongjmpO out of 

2401 signal handlers require rigorous protection in order to be portable. Many of the 

2402 other functions that are excluded from the list are traditionally implemented 

2403 using either the C language mallocO or freeO functions or the C language stan- 
240-1 dard 170 library, both of which traditionally use data structures in a nonreentrant 

2405 manner. Because any combination of different functions using a common data 

2406 structure can cause reentrancy problems, POSIX.l does not define the behavior 

2407 when any unsafe function is called in a signal handler that interrupts any unsafe 

2408 function. 

2409 B.3.3.1.4 Signal Effects on Other Functions 

2410 The most common behavior of an interrupted function after a signal-catching | 

2411 function returns is for the interrupted function to give an [EINTR] error. How- 

2412 ever, there are a number of specific exceptions, including sleepO and certain 

2413 situations with readO and write 0 - 
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The historical implementations of many functions defined by POSIX.l are not 
interruptible, but delay delivery of signals generated during their execution until 
after they complete. This is never a problem for functions that are guaranteed to 
complete in a short (imperceptible to a human) period of time. It is normally 
those functions that can suspend a process indefinitely or for long periods of time 
[e.g., waitO, pause (), sigsuspendO, sleepO, or readOJwritei) on a slow device like a 
terminal] that are interruptible. This permits applications to respond to interac- 
tive signals or to set timeouts on calls to most such functions with alarm (). 
Therefore, implementations should generally make such functions (including ones 
defined as extensions) interruptible. 

Functions not mentioned explicitly as, interruptible may be so on some implemen- 
tations, possibly as an extension where the function gives an IEINTRJ error. 
There are several functions [e.g., getpidO , getuidO ] that are specified as never 
returning an error, which can thu9 never be extended in this way. 

B.3.3.2 Send a Signal to a Process 

The semantics for permission checking for killO differ between System V and 
most other implementations, such as Version 7 or 4.3BSD. The semantics chosen 
for POSIX.l agree with System V. Specifically, a set-user-ID process cannot pro- 
tect itself against signals (or at least not against SIGKILL) unless it changes its 
real user ID. This choice allows the user who starts an application to send it sig- 
nals even if it changes its effective user ID. The other semantics give more power 
to an application that wants to protect itself from the user who ran it. 

Some implementations provide semantic extensions to the killO function when 
the absolute value of pid is greater than some maximum, or otherwise special, 
value. Negative values are a flag to killO- Since most implementations return 
[ESRCH] in this case, this behavior is not included in POSIX. 1, although a con- 
forming implementation could provide such an extension. 

The implementation-defined processes to which a signal cannot be sent may 
include the scheduler or init. " 

Most historical implementations use kill(-l,sig) from a super-user process to 
send a signal to all processes (excluding system processes like init). This use of 
the killO function is for administrative purposes only; portable applications 
should not send signals to processes about which they have no knowledge. In 
addition, there are semantic variations among different implementations that, 
because of the limited use of this feature, were not necessary to resolve by stan- 
dardization. System V implementations also use kill (— l,sig) Irom a 
nonsuper-user process to send a signal to all processes with matching user IDs. 
This use was considered neither sufficiently widespread nor necessary for applica- 
tion portability to warrant inclusion in POSIX.1. 

There was initially strong sentiment to specify that, if pid specifies that a signal 
be sent to the calling process and that signal is not blocked, that signal would be 
delivered before killO returns. This would permit a process to call killO and be 
guaranteed that the call never return. However, historical implementations that 
provide only the signalO interface make only the weaker guarantee in POSIX.1, 
because they only deliver one signal each time a process enters the kernel. 
Modifications to such implementations to support the sigaction 0 interface 
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generally require entry to the kernel following return from a signal-catching func- 
tion, in order to restore the signal mask. Such modifications have the effect of 
satisfying the stronger requirement, at least when sigactioni) is used, but not 
necessarily when signal () is used. The developers of POSIX.1 considered making 
the stronger requirement except when signalO is used, but felt this would be | 
unnecessarily complex. Implementors are encouraged to meet the stronger 
requirement whenever possible. In practice, the weaker requirement is the same , 
except in the rare case when two signals arrive during a very short window. This 
reasoning also applies to a similar requirement for sigprocmask (). 

In 4.2BSD, the SIGCONT signal can be sent to any descendant process regardless 
of user-ID security checks. This allows a job-control shell to continue a job even if 
processes in the job have altered their user IDs (as in the su command). In keep- 
ing with the addition of the concept of sessions, similar functionality is provided 
by allowing the SIGCONT signal to be sent to any process in the same session, 
regardless of user-ID security checks. This is less restrictive than BSD in the 
sense that ancestor processes (in the same session) can now be the recipient. It is 
more restrictive than BSD in the sense that descendant processes that form new 
sessions are now subject to the user-ID checks. A similar relaxation of security is 
not necessary for the other job-control signals since those signals are typically 
sent by the terminal driver in recognition of special characters being typed, the 
terminal driver bypasses all security checks. 

In secure implementations, a process may be restricted from sending a signal to a 
process having a different security label. In order to prevent the existence or 
nonexistence of a process from being used as a covert channel, such processes 
should appear nonexistent to the sender; i.e., [ESRCH] should be returned, rather 
than [ EPERM I, if pid refers only to such processes. 

Existing implementations vary on the result of a killQ with pid indicating an 
inactive process (a terminated process that has not been waited for by its parent). 
Some indicate success on such a call (subject to permission checking), while others 
give an error of (ESRCH J. Since POSIX. l’s definition of process lifetime covers inac- 
tive processes, the [ESRCH] error as described is inappropriate in this case. In 
particular, this means that an application cannot have a parent process check for 
termination of a particular child with killi) [usually this is done with the null sig- 
nal; this can be done reliably with waitpidi)]. 

There is some belief that the name killi) is misleading, since the function is not 
always intended to cause process termination. However, the name is common to 
all historical implementations, and any change would be in conflict with the goal 
of Minimal Changes to Existing Application Code. 


B.3.3.3 Manipulate Signal Sets 

The implementation of the sigemptyseti) [or sigfillseti )] functions could quite trivi- 
ally clear (or set) all the bits in the signal set. Alternatively, it would be reason- 
able to initialize part of the structure, such as a version field, to permit binary 
compatibility between releases where the size of the set varies. For such reasons, 
either sigemptyseti) or sigfillseti) must be called prior to any other use of the sig- 
nal set, even if such use is read-only [e.g., as an argument to sigpendingi )1. This 
function is not intended for dynamic allocation. 


B Rationale and Notes 


Part 1: SYSTEM API [C LANGUAGE] 

2506 The sigfillseti) and sigemptyseti) functions require that the resulting signal set 
2607 include (or exclude) all the signals defined in POSIX.1. Although it is outside the 

2508 scope of POSIX.1 to place this requirement on signals that are implemented as 

2509 extensions, it is recommended that implementation-defined signals also be 

2510 affected by these functions. However, there may be a good reason for a particular 

2611 signal not to be affected. For example, blocking or ignoring an implementation- 

2612 defined signal may have undesirable side effects, whereas the default action for 

2513 that signal is harmless. In such a case, it would be preferable for such a signal to 

2514 be excluded from the signal set returned by sigfillseti ). 

2615 In earlier drafts of POSIX.1 there was no distinction between invalid and unsup- 

2516 ported signals (the names of optional signals that were not supported by an 

2517 implementation were not defined by that implementation). The [EINVAL] error 

2518 was thus specified as a required error for invalid signals. With that distinction, it 

2519 is not necessary to require implementations of these functions to determine 

2620 whether an optional signal is actually supported, as that could have a significant 

2521 performance impact for little value. The error could have been required for 

2622 invalid signals and optional for unsupported signals, but this seemed unneces- 
2523 sarily complex. Thus, the error is optional in both cases. 


2624 B.3.3.4 Examine and Change Signal Action 

2525 Although POSIX.1 requires that signals that cannot be ignored shall not be added 

2526 to the signal mask when a signal-catching function is entered, there is no explicit 

2527 requirement that subsequent calls to sigactioni) reflect this in the information 
2628 returned in the oact argument. In other words, if SIGKILL is included in the 

2529 sajnask field of act, it is unspecified whether or not a subsequent call to sigac- 

2530 tioni) will return with SIGKILL included in the sajnask field of oact . 

2531 The SA.NOCLDSTOP flag, when supplied in the act->sajlags parameter, allows 

2532 overloading SIGCHLD with the System V semantics that each SIGCLD signal indi- 
2633 cates a single terminated child. Most portable applications that catch SIGCHLD 

2534 are expected to install signal-catching functions that repeatedly call the waitpidi) 

2535 function with the WNOHANG flag set, acting on each child for which status is 

2536 returned, until waitpidi) returns zero. If stopped children are not of interest, the 

2537 use of the SA_NOCLDSTOP flag can prevent the overhead from invoking the 

2538 signal-catching routine when they stop. 

2539 Some historical implementations also define other mechanisms for stopping 

2540 processes, such as the ptracei) function. These implementations usually do not 

2541 generate a SIGCHLD signal when processes stop due to this mechanism; however, 

2542 that is beyond the scope of POSIX.1. 

2543 POSIX.1 requires that calls to sigactioni) that supply a NULL act argument 

2544 succeed, even in the case of signals that cannot be caught or ignored (i.e., SIGKILL 

2545 or SIGSTOP). The System V signalO and BSD sigueci) functions return (EINVAL] 

2546 in these cases and, in this respect, their behavior varies from sigactioni). 

2547 POSIX.1 requires that sigactioni) properly save and restore a signal action set up 

2548 by the C Standard {2} signali) function. However, there is no guarantee that the 

2549 reverse is true, nor could there be given the greater amount of information con- 

2550 veyed by the sigaction structure. Because of this, applications should avoid using 

2551 both functions for the same signal in the same process. Since this cannot always 
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2552 be avoided in case of general-purpose library routines, they should always be 

2553 implemented with sigaction (). 

2554 It was intended that the signal () function should be implementable as a library | 

2556 routine using sigactioni). I 

255 « B.3.3.5 Examine and Change Blocked Signals 

2557 When a process’s signal mask is changed in a signal-catching function that is 

2555 installed by sigactionO, the restoration of the signal mask on return from the 

2559 signal-catching function overrides that change [see sigactioni )]. If the signal- , 

2560 catching function was installed with signali), it is unspecified whether this 

2561 occurs. 

2562 See B. 3 . 3.2 for a discussion of the requirement on delivery of signals. 

2663 B.3.3.6 Examine Pending Signals 

2564 There is no additional rationale provided for this subclause. 

2565 B.3.3.7 Wait for a Signal 

2566 Normally, at the beginning of a critical code section, a specified set of signals is 

2567 blocked using the sigprocmaski) function. When the process has completed the 

2568 critical section and needs to wait for the previously blocked signal(s), it pauses by 

2569 calling sigsuspendi ) with the mask that was returned by the sigprocmaski ) call. 

2570 B.3.4 Timer Operations 

2571 B.3.4.1 Schedule Alarm 

2572 Many historical implementations (including Version 7 and System V) allow an 

2573 alarm to occur up to a second early. Other implementations allow alarms up to 

2674 half a second or one clock tick early or do not allow them to occur early at all. The | 

2576 latter is considered most appropriate, since it gives the most predictable behavior, 
2676 especially since the signal can always be delayed for an indefinite amount of time 

2577 due to scheduling. Applications can thus choose the seconds argument as the 

2578 minimum amount of time they wish to have elapse before the signal. 

2579 The term “real time” here and elsewhere [s/eepO, times ()] is intended to mean 

25 so “wall clock” time as common English usage, and has nothing to do with “realtime 

2681 operating systems.” It is in contrast to “virtual time,” which could be misinter- 

2682 preted if just “time” were used. 

2583 In some implementations, including 4 . 3 BSD, very large values of the seconds 

2584 argument are silently rounded down to an implementation-defined maximum 

2585 value. This maximum is large enough (on the order of several months) that the 

2586 effect is not noticeable. 

2587 Application writers should note that the type of the argument seconds and the 

2588 return value of alarmi) is unsigned int. That means that a Strictly Conforming 

2589 POSIX.l Application cannot pass a value greater than the minimum guaranteed 
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2690 value for {UINT_MAX}, which the C Standard (2) sets as 65 535, and any applica- 

2591 tion passing a larger value is restricting its portability. A different type was con- | 

2592 sidered, but historical implementations, including those with a 16-bit int type, | 

2593 consistently use either unsigned int or int . 

2594 Application writers should be aware of possible interactions when the same pro- 

2595 cess uses both the alarmi) and sleepi) functions [see sleepi) and B.3.4.3]. 


2596 B.3.4.2 Suspend Process Execution 

2597 Many common uses of pausei) have timing windows. The scenario involves check- 

2698 ing a condition related to a signal and, if the signal has not occurred, calling 

2699 pausei). When the signal occurs' between the check and the call to pausei ), the 

2600 process often blocks indefinitely. The sigprocmaski) and sigsuspendi) functions 

2601 can be used to avoid this type of problem. 

2602 B.3.4.3 Delay Process Execution 

2603 There are two general approaches to the implementation of the sleepi) function. 

2604 One is to use the alarmi) function to schedule a SIGALRM signal and then 

2605 suspend the process waiting for that signal. The other is to implement an 

2606 independent facility. POSIX .1 permits either approach. 

2607 In order to comply with the wording of the introduction to Section 3 , that no prim- 

2608 itive shall change a process attribute unless explicitly described by POS 1 X. 1 , an 

2609 implementation using SIGALRM must carefully take into account any SIGALRM 

2610 signal scheduled by previous alarmi) calls, the action previously established for 

2611 SIGALRM, and whether SIGALRM was blocked. If a SIGALRM has been scheduled 

2612 before the sleepi) would ordinarily complete, the sleepi ) must be shortened to that 

2613 time and a SIGALRM generated (possibly simulated by direct invocation of the 

2614 signal-catching function) before sleepi) returns. If a SIGALRM has been scheduled 
2616 after the sleepi) would ordinarily complete, it must be rescheduled for the same 

2616 time before sleepi) returns. The action and blocking for SIGALRM must be saved 

2617 and restored. 

2618 Historical implementations often implement the SIGALRM-based version using 

2619 alarmi) and pausei). One such implementation is prone to infinite hangups, as 

2620 described in B. 3 . 4 . 2 . Another such implementation uses the C language setjmpi) 

2621 and longjmpi) functions to avoid that window. That implementation introduces a 

2622 different problem: when the SIGALRM signal interrupts a signal-catching function 

2623 installed by the user to catch a different signal, the longjmpi) aborts that signal- 

2624 catching function. An implementation based on sigprocmaski), alarmi), and sig- 

2625 suspendi) can avoid these problems. 

2626 Despite all reasonable care, there are several very subtle, but detectable and una- 

2627 voidable, differences between the two types of implementations. These are the 

2628 cases mentioned in POSIX .1 where some other activity relating to SIGALRM takes 

2629 place, and the results are stated to be unspecified. All of these cases are 

2630 sufficiently unusual as not to be of concern to most applications. 

2631 (See also the discussion of the term “real time” in B. 3 . 4 . 1 .) 
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2«32 Because sleep () can be implemented using alarm (), the discussion about alarms 

2633 occurring early under B.3.4.1 applies to sleepO as well. 

2634 Application writers should note that the type of the argument seconds and the 

2635 return value of sleep () is unsigned int. That means that a Strictly Conforming 

2636 POSIX.1 Application cannot pass a value greater than the minimum guaranteed 

2637 value for (UINT_MAX}, which the C Standard {2} sets as 65535, and any applica- 

2638 tion passing a larger value is restricting its portability. A different type was con- | 

2639 sidered, but historical implementations, including those with a 16-bit int type, | 

2640 consistently use either unsigned int or int. 

2641 Scheduling delays may cause the process to return from the sleepO function 

2642 significantly after the requested time. In such cases, the return value should be 

2643 set to zero, since the formula (requested time minus the time actually spent) 
26-i4 yields a negative number and sleepO returns an unsigned int. 


2645 B.4 Process Environment 

2646 R.4.1 Process Identification 

2647 B.4. 1.1 Get Process and Parent Process IDs 

2648 There is no additional rationale provided for this subclause. 

2649 B.4.2 User Identification 

2650 B.4.2. 1 Get Real User, Effective User, Real Group, and Effective Group 

2651 IDS 

2652 There is no additional rationale provided for this subclause. 

2653 B.4.2.2 Set User and Group IDs 

2654 The saved set-user-ID capability allows a program to regain the effective user ID 

2655 established at the last exec call. Similarly, the saved set-group-ID capability 

2656 allows a program to regain the effective group ID established at the last exec call. 

2657 These two capabilities are derived from System V. Without them, a program may 

2658 have to run as super-user in order to perform the same functions, because super- 

2659 user can write on the user’s files. This is a problem because such a program can 

2660 write on any user’s files, and so must be carefully written to emulate the permis- 

2661 sions of the calling process properly. 

2662 A process with appropriate privilege on a system with this saved ID capability 

2663 establishes all relevant IDs to the new value, since this function is used to estab- 

2664 lish the identity of the user during login or su. Any change to this behavior 

2665 would be dangerous since it involves programs that need to be trusted. 


2666 The behavior of 4.2BSD and 4.3BSD that allows setting the real ID to the effective 

2667 ID is viewed as a value-dependent special case of appropriate privilege. 

2668 B.4.2.3 Get Supplementary Group IDs 

2669 The related function setgroups () is a privileged operation and therefore is not 

2670 covered by POSIX.1. 

2671 As implied by the definition of supplementary groups, the effective group ID may | 

2672 appear in the array returned by getgroupsO or it may be returned only by 

2673 getegidO- Duplication may exist, but the application needs to call getegidO to be 

2674 sure of getting all of the informatiqn. Various implementation variations and | 

2676 administrative sequences will cause the set of groups appearing in the result of | 

2676 getgroupsO to vary in order and as to whether the effective group ID is included, | 

2677 even when the set of groups is the same (in the mathematical sense of “set”). (The | 

2678 history of a process and its parents could affect the details of result.) I 

2679 Applications writers should note that (NGROUPS_MAX) is not necessarily a con- | 

2680 stant on all implementations. I 

2681 B.4.2.4 Get User Name 

2682 The getloginO function returns a pointer to the user’s login name. The same user | 

2683 ID may be shared by several login names. If it is desired to get the user database | 

2684 entry that is used during login, the result of getloginO should be used to provide | 

2685 the argument to the getpwnamO function. (This might be used to determine the | 

2686 user’s login shell, particularly where a single user has multiple login shells with | 

2687 distinct login names, but the same user ID.) I 

2688 The information provided by the cuseridO function, which was originally defined | 

2689 in IEEE Std 1003.1-1990 and subsequently removed, can be obtained by the | 

2690 following: I 

2691 getpwuid(geteuid() ) ^ ' 

2692 while the information provided by historical implementations of cuseridO can be | 

2693 obtained by: I 

2694 getpwuid (getuid ( ) ) ! 

2695 B.4.3 Process Groups 

2696 B.4.3. 1 Get Process Group ID 

2697 4.3BSD provides a getpgrpO function that returns the process group ID for a 

2698 specified process. Although this function is used to support job control, all known 

2699 job-control shells always specify the calling process with this function. Thus, the 

2700 simpler System V getpgrpO suffices, and the added complexity of the 4.3BSD 

2701 getpgrp () has been omitted from POSIX.1. 
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2702 B.4.3.2 Create Session and Set Process Group ID 

2703 The setsidO function is similar to the setpgrp () function of System V. System V, 

2704 without job control, groups processes into process groups and creates new process 

2705 groups via setpgrp (); only one process group may be part of a login session. 

2706 Job control allows multiple process groups within a login session. In order to 

2707 limit job-control actions so that they can only affect processes in the same login 

2708 session, POSIX. 1 adds the concept of a session that is created via setsidO. The set- 

2709 sid() function also creates the initial process group contained in the session. 

2710 Additional process groups can be created via the setpgidO function. A System V 

2711 process group would correspond to a POSIX.1 session containing a single POSIX.1 

2712 process group. Note that this function requires that the calling process not be a 

2713 process group leader. The usual way to ensure this is true is to create a new pro- 

2714 cess with forkO and have it call setsidO • The forkO function guarantees that the 

2715 process ID of the new process does not match any existing process group ID. 

2716 B.4.3.3 Set Process Group ID for Job Control 

2717 The setpgidO function is used to group processes together for the purpose of sig- 

2718 naling, placement in foreground or background, and other job-control actions. See 

2719 B.2.2.2. 

2720 The setpgidO function is similar to the setpgrpO function of 4.2BSD, except that 

2721 4 . 2 BSD allowed the specified new process group to assume any value. This 

2722 presents certain security problems and is more flexible than necessary to support 

2723 job control. 

2724 To provide tighter security, setpgidO only allows the calling process to join a pro- 

2725 cess group already in use inside its session or create a new process group whose 

2726 process group ID was equal to its process ID. 

2727 When a job-control shell spawns a new job, the processes in the job must be 

2728 placed into a new process group via setpgidO . There are two timing constraints 

2729 involved in this action: 

2730 (1) The new process must be placed in the new process group before the 

2731 appropriate program is launched via one of the exec functions. 

2732 (2) The new process must be placed in the new process group before the shell 

2733 can correctly send signals to the new process group. 

2734 To address these constraints, the following actions are performed: The new 

2735 processes call setpgidO to alter their own process groups after forkO but before 

2736 exec. This satisfies the first constraint. Under 4.3BSD, the second constraint is 

2737 satisfied by the synchronization property of vforkO’, that is, the shell is suspended 

2738 until the child has completed the exec, thus ensuring that the child has completed 

2739 the setpgidO. A new version of forkO with this same synchronization property | 

2740 was considered, but it was decided instead to merely allow the parent shell pro- | 

2741 cess to adjust the process group of its child processes via setpgidO . Both timing 

2742 constraints are now satisfied by having both the parent shell and the child 

2743 attempt to adjust the process group of the child process; it does not matter which 

2744 succeeds first. 
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2745 Because it would be confusing to an application to have its process group change 

2746 after it began executing (i.e., after exec) and because the child process would 

2747 already have adjusted its process group before this, the [EACCESJ error was added 

2748 to disallow this. 

2749 One nonobvious use of setpgidO is to allow a job-control shell to return itself to its 

2750 original process group (the one in effect when the job-control shell was executed). 

2751 A job-control shell does this before returning control back to its parent when it is 

2752 terminating or suspending itself as a way of restoring its job control “state’ back 

2753 to what its parent would expect. (Note that the original process group of the job- 

2754 control shell typically matches the process group of its parent, but this is not 

2755 necessarily always the case.) See also B. 7.2.4. 


2756 B.4.4 System Identification 


i 


2757 B.4.4. 1 System Name 

2758 The values of the structure members are not constrained to have any relation to 

2759 the version of POSIX.1 implemented in the operating system. An application 

2760 should instead depend on UPOSIX^VERSION) and related constants defined in 2.9. 

. 2761 POSIX.1 does not define the sizes of the members of the structure and permits 

2762 them to be of different sizes, although most implementations define them all to be 

2763 the same size: eight bytes plus one byte for the string terminator. That size for 

2764 nodename is not enough for use with many networks. 

2765 The uname 0 function is specific to System III, System V, and related implementa- 

2766 tions, and it does not exist in Version 7 or 4.3BSD. The values it returns are set 

, 2767 at system compile time in those historical implementations. I 

2768 4.3BSD has gethostnameO and gethostidO, which return a symbolic name and a 

2769 numeric value, respectively. There are related sethostnanie () and sethostidO 

2770 functions that are used to set the values the other two functions return. The 

2771 length of the host name is limited to 31 characters in most implementations and 

2772 the host ID is a 32-bit integer. 


2773 B.4.5 Time 

2774 The timeO function returns a value in seconds (type time_t) while times () returns 

2776 a set of values in clock ticks (type clock Jt). Some historical implementations, such | 

2776 as 4.3BSD, have mechanisms capable of returning more precise times [see the 

2777 description of gettimeofdayO in B.4.5. 1]. A generalized timing scheme to unify 

2778 these various timing mechanisms has been proposed but not adopted in POSIX.1. | 

2779 B.4.5. 1 Get System Time 

2780 Implementations in which timej is a 32-bit signed integer (most historical imple- 

2781 mentations) will fail in the year 2038. This version of POSIX.1 does not address | 

2782 this problem. However, the use of the new timejt type is mandated in order to | 

2783 ease the eventual fix. 1 
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2784 The use of the header ctime . h>, instead of <sys/types . h>, allows compatibil- 

2785 ity with the C Standard (2). 

2780 Many historical implementations (including Version 7) and the 1984 /usr /group 

2787 Standard {B59} use long instead of timej. POSIX.l uses the latter type in order 

2788 to agree with the C Standard {2}. 

2789 4.3BSD includes timeO only as an interface to the more flexible gettimeofday () 

2790 function. 

2791 B.4.5.2 Get Process Times 

2792 The accuracy of the times reported is intentionally left unspecified to allow imple- 

2793 mentations flexibility in design, from uniprocessor to multiprocessor networks. 

2794 The inclusion of times of child processes is recursive, so that a parent process may 

2795 collect the total times of all of its descendants. But the times of a child are only 

2796 added to those of its parent when its parent successfully waits on the child. Thus, 

2797 it is not guaranteed that a parent process will always be able to see the total 

2798 times of all its descendants. 

2799 (See also the discussion of the term “real time” in B. 3 . 4 . 1 .) 

28 00 If the type clockjt is defined to be a signed 32-bit integer, it will overflow in some- 

2801 what more than a year if there are 60 clock ticks per second, or less than a year if | 

2802 there are 100. There are individual systems that run continuously for longer than 

2803 that. POSIX. 1 permits an implementation to make the reference point for the 

2804 returned value be the startup time of the process, rather than system startup 

2805 time. 

2806 The term “charge” in this context has nothing to do with billing for services. The 

2807 operating system accounts for time used in this way. That information must be 

2808 correct, regardless of how that information is used. 

2809 B.4.6 Environment Variables 

28 10 B.4.6. 1 Environment Access 

28 11 Additional functions putenv () and clearenvO were considered but rejected because 

2812 they were considered to be more oriented towards system administration than 

2813 ordinary application programs. This is being reconsidered for an amendment to | 

2814 POSIX. 1 because uses from within an application have been identified since the | 

2815 decision was made. 

2816 It was proposed that this function is properly part of Section 8. It is an extension | 
2ai7 to a function in the C Standard (2). Because this function should be available | 

2818 from any language, not just C, it appears here, to separate it from the material in j 

2819 Section 8, which is specific to the C binding. (The localization extensions to C are 

2820 not, at this time, appropriate for other languages.) 
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2821 B.4.7 Terminal Identification 

2822 The difference between ctermidO and ttynameO is that ttyname () must be passed 

2823 a file descriptor and returns the pathname of the terminal associated with that 

2824 file descriptor, while ctermidO returns a string (such as /dev/ tty) that will refer 
2826 to the controlling terminal if used as a pathname. Thus ttyname 0 is useful only if 

2826 the process already has at least one file open to a terminal. 

2827 The historical value of ctermidO is /dev/ tty; this is acceptable. The ctermidO 

2828 function should not be used to determine if a process actually has a controlling 

2829 terminal, but merely the name that would be used. 

2830 B.4.7. 1 Generate Terminal Pathname 

2831 L_ctermid must be defined appropriately for a given implementation and must be 

2832 greater than zero so that array declarations using it are accepted by the compiler. 

2833 The value includes the terminating null byte. 

2834 B.4.7.2 Determine Terminal Device Name 

2835 The term “terminal” is used instead of the historical term “terminal device” in 

2836 order to avoid a reference to an undefined term. 

2837 B.4.8 Configurable- System Variables 

2838 This subclause was added in response to requirements of application developers | 

2839 and of system vendors who deal with many international system configurations. | 

2840 It is closely related to B.5.7 as well. 

2841 Although a portable application can run on all systems by never demanding more 

2842 resources than the minimum values published in POSIX.l, it is useful for that 

2843 application to be able to use the actual value for the quantity of a resource avail- 

2844 able on any given system. To doJ-his, the application will make use of the value of 

2845 a symbolic constant in <limits . h> or <unistd.h>. 

2846 However, once compiled, the application must still be able to cope if the amount of 

2847 resource available is increased. To that end, an application may need a means of 

2848 determining the quantity of a resource, or the presence of an option, at execution 

2849 time. 

2850 Two examples are offered: 

2851 (1) Applications may wish to act differently on systems with or without job 

2862 control. Applications vendors who wish to distribute only a single binary 

2853 package to all instances of a computer architecture would be forced to 

2854 assume job control is never available if it were to rely solely on the 

2855 cunistd . h> value published in POSIX.1. 

2856 (2) International applications vendors occasionally require knowledge of the | 

2857 number of clock ticks per second. Without the facilities of this subclause, | 

2858 they would be required to either distribute their applications partially in | 

2859 source form or to have 50 Hz and 60 Hz versions for the various countries | 

2860 in which they operate. 
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It is the knowledge that many applications are actually distributed widely in exe- 
cutable form that lead to this facility. If limited to the most restrictive values in 
the headers, such applications would have to be prepared to accept the most lim- 
ited environments offered by the smallest microcomputers. Although this is 
entirely portable, there was a consensus that they should be able to take advan- 
tage of the facilities offered by large systems, without the restrictions associated 
with source and object distributions. 

During the discussions of this feature, it was pointed out that it is almost always 
possible for an application to discern what a value might be at run-time by suit- 
ably testing the various interfaces themselves. And, in any event, it could always 
be written to adequately deal with error returns from the various functions. In 
the end, it was felt that this imposed an unreasonable level of complication and 
sophistication on the application writer. 

This run-time facility is not meant to provide ever-changing values that applica- 
tions will have to check multiple times. The values are seen as changing no more 
frequently than once pier system initialization, such as by a system administrator 
or operator with an automatic configuration program. POSIX. 1 specifies that they 
shall not change within the lifetime of the process. 

Some values apply to the system overall and others vary at the file system or 
directory level. These latter are described in B.5.7. 

B.4.8.1 Get Configurable System Variables 

Note that all values returned must be expressible as integers. String values were 
considered, but the additional flexibility of this approach was rejected due to its 
added complexity of implementation and use. 

Some values, such as (PATH.MAX), are sometimes so large that they must not be 
used to, say, allocate arrays. The sysconfi) function will return a negative value 
to show that this symbolic constant is not even defined in this case. 

B.4.8.1. 1 Special Symbol {CLK__TCK} 

(CLK.TCK) appears in POSIX.l for backwards compatibility with IEEE Std 
1003.1-1988. Its use is obsolescent. 

B.4.8.2 Get Password From User 

The getpassi) function was explicitly excluded from POSIX1 because it was found 
that the name was misleading, and it provided no functionality that the user 
could not easily implement within POSIX 1. The implication of some form of secu- 
rity, which was not actually provided, exceeded the small gain in convenience. 
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2896 B.5 Files and Directories 

2897 See pathname resolution . 

2898 The wording regarding the group of a newly created regular file, directory, or 

2899 FIFO in openO, mkdirO, mkfifoO, respectively, defines the two acceptable 

2900 behaviors in order to permit both the System V (and Version 7) behavior (in which 

2901 the group of the new object is set to the effective group ID of the creating process) 

2902 and the 4.3BSD behavior (in which the new object has the group of its parent 

2903 directory). An application that needs a file to be created specifically in one or the 

2904 other of the possible groups should use chowni,) to ensure the new group regard- 

2905 less of the style of groups the interface implements. Most applications will not 

2906 and should not be concerned with the group ID of the file. 

2907 B.5.1 Directories 

2908 Historical implementations prior to 4.2BSD had no special functions, types, or 

2909 headers for directory access. Instead, directories were read with readO and each 

2910 program that did so had code to understand the internal format of directory files. 

2911 Many such programs did not correctly handle the case of a maximum-length (his- 

2912 torically fourteen character) filename and would neglect to add a null character 

2913 string terminator when doing comparisons. The access methods in POSIX.1 elim- 

2914 inate that bug, as well as hiding differences in implementations of directories or 
2916 file systems. 

2916 The directory access functions originally selected for POSIX.1 were derived from 

2917 4.2BSD, were adopted in System V Release 3, and are in SVID (B39) Volume 3, 

2918 with the exception of a type difference for the d_ino field. That field represents 

2919 implementation-dependent or even file system-dependent information (the i-node 

2920 number in most implementations). Since the directory access mechanism is 

2921 intended to be implementation-independent, and since only system programs, not 

2922 ordinary applications, need to know about the i-node number (or file serial 

2923 number) in this context, the djno field does not appear in POSIX.l. Also, pro- 

2924 grams that want this information" can get it with stat (). 

2926 B.5.1.1 Format of Directory Entries 

2926 Information similar to that in the header <dirent.h> is contained in a file 

2927 <sys/dir.h> in 4.2BSD and 4.3BSD. The equivalent in these implementations 

2928 of struct dirent from POSIX.l is struct direct. The filename was changed because 

2929 the name <sys/dir.h> was also used in earlier implementations to refer to 

2930 definitions related to the older access method; this produced name conflicts. The 

2931 name of the structure was changed because POSIX.1 does not completely define 

2932 what is in the structure, so it could be different on some implementations from 

2933 struct direct . 

2934 The name of an array of char of an unspecified size should not be used as an 

2935 lvalue. Use of 

2936 sizeof (d_name) 

2937 is incorrect; use 
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2938 strlen (d_name) 

2939 instead. 

2940 The array of char dname is not a fixed size. Implementations may need to | 

2941 declare struct dirent with an array size for djiame of 1, but the actual number ot 

2942 characters provided matches (or only slightly exceeds) the length of the file name. 

2943 Currently, implementations are excluded if they have d_name with type char *. 

2944 Lacking experience of such implementations, the developers of POSIX.1 declined | 
2946 to try to describe in standards language what to do if either type were permitted. 

2946 B.5.1.2 Directory Operations 

2947 Based on historical implementations, the rules about file descriptors apply to 
294s directory streams as well. However, POSIX.1 does not mandate that the directory 

2949 stream be implemented using file descriptors. The description of opendiri) 

2950 clarifies that if a file descriptor is used for the directory stream it is mandatory 

2951 that closediri) deallocate the file descriptor. When a file descnptor is used to 

2952 implement the directory stream, it behaves as if the FD_CLOEXEC had been set 

2953 for the file descriptor. 

2954 The returned value of readdiri) merely represents a directory entry.. No 
2966 equivalence should be inferred. 

2966 The directory entries for dot and dot-dot are optional. POSIX.1 does not provide a | 

2957 way to test a priori for their existence because an application that is portable. 

2958 must be written to look for (and usually ignore) those entries. Writing code that 
2969 presumes that they are the first two entries does not always work, as many imple- 

2960 mentations permit them to be other than the first two entries, with a normal 

2961 entry preceding them. There is negligible value in providing a way to determine 

2962 what the implementation does because the code to deal with dot and dot-dot must 

2963 be written in any case and because such a flag would add to the list of those flags 

2964 (which has proven in itself to be objectionable) and might be abused. I 

2965 Since the structure and buffer allocation, if any, for directory operations are 

2966 defined by the implementation, POSIX.1 imposes no portability requirements for 

2967 erroneous program constructs, erroneous data, or the use of indeterminate values 

2968 such as the use or referencing of a dirp value or a dirent structure value after a 

2969 directory stream has been closed or after a forki) or one of the exec function cal s. 

2970 Historical implementations of readdiri ) obtain multiple directory entries on a sin- 

2971 gle read operation, which permits subsequent readdiri) operations to operate 

2972 from the buffered information. Any wording that required each successful read- 

2973 dir{) operation to mark the directory st_atime field for update would militate 

2974 against the historical performance-oriented implementations. 

2975 Since readdiri ) returns NULL both: 

2976 (1) When it detects an error, and 

2977 (2) When the end of the directory is encountered 

2978 an application that needs to tell the difference must set errno to zero before the 

2979 call and check it if NULL is returned. Because the function must not change 
2900 errno in case (2) and must set it to a nonzero value in case (1), a zero errno after a 
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2981 call returning NULL indicates end of directory, otherwise an error. 

2982 Routines to deal with this problem more directly were proposed: 

2983 int derror (dirp) 

2984 DIR * dirp ; 

2986 void clearderr (dirp) 

2986 dir *dirp; 

2987 The first would indicate whether an error had occurred, and the second would 

2988 clear the error indication. The simpler method involving errno was adopted 

2989 instead by requiring that readdiri) not change errno when end-of-directory is 

2990 encountered. 

2991 Historical implementations include two more functions: 

2992 long telldir (dirp) 

2993 DIR *dirp; 

2994 void seekdir (dirp, loc) 

2996 DIR *dirp ; 

2996 long loc; 

2997 The telldiri) function returns the current location associated with the named 

2998 directory stream. 

2999 The seekdirO function sets the position of the next readdirO operation on the 

3000 directory stream. The new position reverts to the one associated with the direc- 

3001 tory stream when the telldiri ) operation was performed. 

3002 These functions have restrictions on their use related to implementation details. 

3003 Their capability can usually be accomplished by saving a filename found by read- 

3004 diri) and later using rewinddiri) and a loop on readdiri) to relocate the position 

3005 from which the filename was saved. Though this method is probably slower than 

3006 using seekdiri) and telldiri), there are few applications in which the capability is 

3007 needed. Furthermore, directory systems that are implemented using technology 

3008 such as balanced trees, where the order of presentation may vary from access to 

3009 access, do not lend themselves well to any concept along these lines. For these 

3010 reasons, seekdiri) and telldiri ) are not included in POSIX.1. 

sou An error or signal indicating that a directory has changed while open was con- 
3012 sidered but rejected. 


3013 B.5.1.3 Set Position of Directory Stream 

sow The seekdiri) and telldiri) functions were proposed for inclusion in POSIX.1, but 

3015 were excluded because they are inherently unreliable when all the possible con- 

3016 forming implementations of the rest of POSIX.1 were considered. The problem is 

3017 that returning to a given point in a directory is quite difficult to describe formally, 

3018 in spite of its intuitive appeal, when systems that used B-trees, hashing functions, 

3019 or other similar mechanisms for directory search are considered. 

3020 Even the simple goal of attempting to visit each directory entry that is unmodified 

3021 between the opendirO and closedirO calls exactly once is difficult to implement 

3022 reliably in the face of directory compaction and reorganization. 
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3023 Since the primary need for seekdirO and telldirO is to implement file tree walks, 

3024 and since such a function is likely to be included in a future revision of POSIX. 1, 

3025 and since in that more constrained context it appears that at least the goal of 

3026 visiting unmodified nodes exactly once can be achieved, it was felt that waiting for 

3027 the development of that function best served all the constituencies. 

302H B.5.2 Working Directory 

3029 B.5.2. 1 Change Current Working Directory 

3030 The chdir( ) function only affects the working directory of the current process. 

3031 The result if a NULL argument is passed to chdir( ) is left implementation defined 

3032 because some implementations dynamically allocate space in that case. 

3033 B.5.2.2 Working Directory Pathname 

3034 Since the maximum pathname length is arbitrary unless (PATH_MAX) is defined, 

3035 an application generally cannot supply a buf with size {{PATH_MAX} + 1). 

3036 Having getcwdO take no arguments and instead use the C function malloci ) to 

3037 produce space for the returned argument was considered. The advantage is that 

3038 getcwdO knows how big the working directory pathname is and can allocate an 

3039 appropriate amount of space. But the programmer would have to use the C func- 

3040 tion freeO to free the resulting object, or each use of getcwdO would further 

3041 reduce the available memory. Also, mallocQ and freeO are used nowhere else in 

3042 P0SIX.1. Finally, getcwdO is taken from the SVID {B39}, where it has the two 

3043 arguments used in POSIX 1. 

3044 The older function getwdO was rejected for use in this context because it had only 

3046 a buffer argument and no size argument, and thus had no way to prevent 

3046 overwriting the buffer, except to depend on the programmer to provide a large 

3047 enough buffer. 

3048 The result if a NULL argument is passed to getcwdO is left implementation 

3049 defined because some implementations dynamically allocate space in that case. 

3050 If a program is operating in a directory where some (grand)parent directory does 

3061 not permit reading, getcwdO may fail, as in most implementations it must read 

3052 the directory to determine the name of the file. This can occur if search, but not 

3053 read, permission is granted in an intermediate directory, or if the program is 

3054 placed in that directory by some more privileged process (e.g., login). Including 

3056 this error, [EACCES], makes the reporting of the error consistent and warns the 

3056 application writer that getcwdO can fail for reasons beyond the control of the 

3067 application writer or user. Some implementations can avoid this occurrence [e.g., 

3058 by implementing getcwdO using pwd, where pwd is a set-user-root process], thus 

3059 the error was made optional. 

3060 Because POSIX.l permits the addition of other errors, this would be a common 

3061 addition and yet one that applications could not be expected to deal with without 

3062 this addition. 


256 


B Rationale and Notes 


Part 1: SYSTEM API [C LANGUAGE] 


ISO/IEC 9946-1: 1990 
IEEE Std 1003.1-1990 


3063 Some current implementations use {PATH_MAX}+2 bytes. These will have to be 

3064 changed. Many of those same implementations also may not diagnose the 

3065 [ERANGE] error properly or deal with a common bug having to do with newline in 

3066 a directory name (the fix to which is essentially the same as the fix for using +1 

3067 bytes), so this is not a severe hardship. 

3068 B.5.2.3 Change Process’s Root Directory I 

3069 The chrootO function was excluded from POSIX.l on the basis that it was not use- | 

3070 ful to portable applications. In particular, creating an environment in which an | 

3071 application could run after executing a chrootO call is well beyond the current | 

3072 scope of POSIX.l. \ I 

3073 B.5.3 General File Creation 

3074 Because there is no portable way to specify a value for the argument indicating 
3076 the file mode bits (except zero), <sys/stat.h> is included with the functions 

3076 that reference mode bits. 

3077 B.5.3. 1 Open a File 

3078 Except as specified in POSIX.l, the flags allowed in oflag are not mutually 

3079 exclusive and any number of them may be used simultaneously. 

3080 Some implementations permit opening FIFOs with 0_RDWR. Since FIFOs could 

3081 be implemented in other ways, and since two file descriptors can be used to the 

3082 same effect, this possibility is left as undefined. 

3083 See B.4.2.3 about the group of a newly created file. 

3084 The use of openO to create a regular file is preferable to the use of creatO because 

3085 the latter is redundant and included only for historical reasons. 

3086 The use of the 0_TRUNC flag on FIFOs and directories [pipes cannot be open ()-edl 

3087 must be permissible without unexpected side effects I e.g., creatO on a FIFO must 

3088 not remove data]. Because terminal special files might have type-ahead data | 

3089 stored in the buffer, 0_TRUNC should not affect their content, particularly if a | 

3090 program that normally opens a regular file should open the current controlling | 

3091 terminal instead. Other file types, particularly implementation-defined ones, are 

3092 left implementation defined. 

3093 Implementations may deny access and return [EACCES] for reasons other than 

3094 just those listed in the [EACCES] definition. 

3095 The 0_NOCTTY flag was added to allow applications to avoid unintentionally 

3096 acquiring a controlling terminal as a side effect of opening a terminal file. 

3097 POSIX 1 does not specify how a controlling terminal is acquired, but it allows an 

3098 implementation to provide this on openO if the 0_NOCTTY flag is not set and 

3099 other conditions specified in 7. 1.1.3 are met. The 0_NOCTTY flag is an effective 

3100 no-op if the file being opened is not a terminal device. 

3101 In historical implementations the value of 0_RDONLY is zero. Because of that, it 

3102 is not possible to detect the presence of 0_RDONLY and another option. Future 
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3103 implementations should encode OJRDONLY and O.WRONLY as bit flags so that: 

3104 CLRDONLY I OJWRONLY == 0 _RDWR 

3105 See the rationale for the change from 0 _NDELAY to 0 _NONBLOCK in B. 6 . 

3106 B.5.3.2 Create a New File or Rewrite an Existing One 

3107 The creat () function is redundant. Its services are also provided by the open() 

3108 function. It has been included primarily for historical purposes since many exist- 

3109 ing applications depend on it. It is best considered a part of the C binding rather 

3 110 than a function that should be provided in other languages. 

sin B.5.3.3 Set File Creation Mask 

3 11 2 Unsigned argument and return types for umask () were proposed. The return 

3 11 3 type and the argument were both changed to modcj. 

3 11 4 Historical implementations have made use of additional bits in cmask for their 
3116 implementation-specific purposes. The addition of the text that the meaning of 

3116 other bits of the field are implementation defined permits these implementations 

3117 to conform to POSIX. 1 . 

3118 B.5.3.4 Link to a File 

3 11 9 See B. 2 . 2 . 2 . 

3120 Linking to a directory is restricted to the super-user in most historical implemen- 

3121 tations because this capability may produce loops in the file hierarchy or other- 

3122 wise corrupt the file system. POSIX.l continues that philosophy by prohibiting 

3123 Link() and unlink () from doing this. Other functions could do it if the implemen- 

3124 tor designed such an extension. 

3125 Some historical implementations allow linking of files on different file systems. 

3126 Wording was added to explicitly allow this optional behavior. Symbolic links are | 

3127 not discussed by POSIX.l. The exception for cross-file system links is intended to | 

3128 apply only to links that are programmatically indistinguishable from “hard” links, j 

3129 B.5.4 Special File Creation 

3130 B.5.4. 1 Make a Directory 

3131 See B. 2 . 5 . 

3132 The mkdir() function originated in 4 . 2 BSD and was added to System V in 

3133 Release 3 . 0 . 

3134 4 . 3 BSD detects [ENAMETOOLONG]. 

3135 See B. 4 . 2.3 about the group of a newly created directory. 
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3136 B.5.4.2 Make a FIFO Special File 

3137 The syntax of this routine is intended to maintain compatibility with historical | 

3138 implementations of mknod{). The latter function was included in the 1984 \ 

3139 / usr /group Standard {B59}, but only for use in creating FIFO special files. The 

3140 mknodi) function was excluded from POSIX 1 as implementation defined and 

3141 replaced by mkdir( ) and mkfifoi ). 

3142 See B.4.2.3 about the group of a newly created FIFO. 

3143 B.5.5 File Removal 

\ 

3144 The rmdir() and rename^) functions originated in 4.2BSD, and they used 
3146 [ENOTEMPTY] for the condition when the directory to be removed does not exist 

3146 or new already exists. When the 1984 /usr /group Standard (B59) was published, 

3147 it contained [EEXIST] instead. When these functions were adopted into System V, | 

3148 the 1984 / usr / group Standard (B59) was used as a reference. Therefore, several | 
i 3149 existing applications and implementations support/use both forms, and no agree- | 

3160 ment could be reached on either value. All implementations are required to sup- j 

3151 ply both [EEXIST] and [ENOTEMPTY] in <errno . h> with distinct values so that 

3152 applications can use both values in C language case statements. 

3153 B.5.5. 1 Remove Directory Entries 

3164 Unlinking a directory is restricted to the super-user in many historical implemen- 
3156 tations for reasons given in B.5.3.4. But see B.5.5.3. 

3156 The meaning of [EBUSY] in historical implementations is “mount point busy.” 

3157 Since POSIX.l does not cover the system administration concepts of mounting and 

3158 unmounting, the description of the error was changed to “resource busy.” (This 

3159 meaning is used by some device drivers when a second process tries to open an 

3160 exclusive use device.) The wording is also intended to allow implementations to 

3161 refuse to remove a directory ijf.it is the root or current working directory of any 

3162 process. 

3163 B.5.5.2 Remove a Directory 

3164 See also B.5.5 and B.5.5. 1. 

3165 B.5.5.3 Rename a File 

3166 This rename () function is equivalent for regular files to that defined by the 

3167 C Standard (2). Its inclusion here expands that definition to include actions on 

3168 directories and specifies behavior when the new parameter names a file that 

3169 already exists. That specification requires that the action of the function be 
3no atomic. 

3171 One of the reasons for introducing this function was to have a means of renaming 

3172 directories while permitting implementations to prohibit the use of linkO and 

3173 unlinkO with directories, thus constraining links to directories to those made by 

3174 mkdir(). 
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3176 The specification that if old and new refer to the same file describes existing, 

3176 although undocumented, 4.3BSD behavior. It is intended to guarantee that: 

3177 rename ("x", "x") ; 

3178 does not remove the file. 

3179 Renaming dot or dot-dot is prohibited in order to prevent cyclical file system 

3180 paths. 

3181 See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in B.5.5 and 

3182 1EBUSY] in B.5.5. 1. For a discussion of [EXDEV], see B.5.3.4. 


3183 B.5.6 File Characteristics 

3184 The ustati) function, which appeared in the 1984 /usr /group Standard (B59) and 
3186 is still in the SVID (B39), was excluded from POSIX.1 because it is: 

3186 — Not reliable. The amount of space available can change between the time 

3187 the call is made and the time the calling process attempts to use it. 

3188 — Not required. The only known program that uses it is the text editor ed. 

3189 — Not readily extensible to networked systems. 

3190 B.5.6.X File Characteristics: Header and Data Structure 

3191 See B.2.5. 

3192 A conforming C language application must include <sys/stat .h> for functions 

3193 that have arguments or return values of type modejt, so that symbolic values for 

3194 that type can be used. An alternative would be to require that these constants 
3196 are also defined by including <sys/types . h>. 

3196 The S_ISUID and S_ISGID bits may be cleared on any write, not just on open(), as 

3197 some historical implementations do it. 

3198 System calls that update the time entry fields in the stat structure must be docu- 

3199 mented by the implementors. POSIX.1 conforming systems should not update the 

3200 time entry fields for functions listed in POSIX.1 unless the standard requires that 

3201 they do, except in the case of documented extensions to the standard. 

3202 Note that st_dev must be unique within a Local Area Network (LAN) in a “system” 

3203 made up of multiple computers’ file systems connected by a LAN. 

3204 Networked implementations of a POSIX.1 system must guarantee that all files 
3206 visible within the file tree (including parts of the tree that may be remotely 

3206 mounted from other machines on the network) on each individual processor are 

3207 uniquely identified by the combination of the st_ino and st_dev fields. 

3208 B.5.6.2 Get File Status 

3209 The intent of the paragraph describing “additional or alternate file access control 

3210 mechanisms is to allow a secure implementation where a process with a label 

3211 that does not dominate the file’s label cannot perform a stati) function. This is 

3212 not related to read permission; a process with a label that dominates the file’s 
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3213 label will not need read permission. An implementation that supports write-up 

3214 operations could fail fstati) function calls even though it has a valid file descriptor 
3216 open for writing. 

3216 B.5.6.3 File Accessibility 

3217 In early drafts of POSIX. 1 , some inadequacies in the access 0 function led to the 

3218 creation of an e access () function because: 

3219 ( 1 ) Historical implementations of accessO do not test file access correctly 

3220 when the process’s real user IB, is super-user. In particular, they always 

3221 return zero when testing execute permissions without regard to whether 

3222 the file is executable. 

3223 (2) The super-user has complete access to all files on a system. As a conse- 

3224 quence, programs started by the super-user and switched to the effective 

3226 user ID with lesser privileges cannot use access() to test their file access 

3226 permissions. 

3227 However, the historical model of eaccessi ) does not resolve problem ( 1 ), so POSIX .1 

3228 now allows accessi) to behave in the desired way because several implementa- 

3229 tions have corrected the problem. It was also argued that problem ( 2 ) is more 

3230 easily solved by using open(), chdir() t or one of the exec functions as appropriate 

3231 and responding to the error, rather than creating a new function that would not 

3232 be as reliable. Therefore, eaccessi) was taken back out of POSIX. 1 . 

3233 Secure implementations will probably need an extended accessO- like function, but 

3234 there were not enough of the requirements to define it yet. This could be pro- 

3235 posed as an extension for a future amendment to POSIX. 1 . 

3236 The sentence concerning appropriate privileges and execute permission bits 

3237 reflects the two possibilities implemented by historical implementations when 

3238 checking super-user access for X^OK. 


B. 5.6.4 Change File Modes 

POSIX.1 specifies that the S_ISGID bit is cleared by chmod() on a regular file 
under certain conditions. This is specified on the assumption that regular files 
may be executed, and the system should prevent users from making executable 
setgid files perform with privileges that the caller does not have. On implementa- 
tions that support execution of other file types, the S.ISGID bit should be cleared 
for those file types under the same circumstances. 

Implementations that use the S_ISUID bit to indicate some other function (for 
example, mandatory record locking) on nonexecutable files need not clear this bit 
on writing. They should clear the bit for executable files and any other cases 
where the bit grants special powers to processes that change the file contents. 
Similar comments apply to the S.ISGID bit. 
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3261 R.5.6.5 Change Owner and Group of File 

3252 System III and System V allow a user to give away files; that is, the owner of a file 

3253 may change its user ID to anything. This is a serious problem for implementa- 

3254 tions that are intended to meet government security regulations. Version 7 and 

3255 4.3BSD permit only the super-user to change the user ID of a file. Some govern- 

3256 ment agencies (usually not ones concerned directly with security) find this limita- 

3257 tion too confining. POSIX.l uses “may” to permit secure implementations while 

3258 not disallowing System V. 

3259 System III and System V allow the owner of a file to change the group ID to any- 

3260 thing. Version 7 permits only the super-user to change the group ID of a file. 

3261 4.3BSD permits the owner to change the group ID of a file to its effective group ID 

3262 or to any of the groups in the list of supplementary group IDs, but to no others. 

3263 Although chown () can be used on some systems by the file owner to change the 

3264 owner and group to any desired values, the only portable use of this function is to 

3265 change the group of a file to the effective GID of the calling process or to a member 

3266 of its group set. 

3267 The decision to require that, for nonprivileged processes, the S_ISUID and 

3268 S_ISGID bits be cleared on regular files, but only may be cleared on nonregular 

3269 files, was to allow plans for using these bits in implementation-specified manners 

3270 on directories. Similar cases could be made for other file types, so POSIX.l does 

3271 not require that these bits be cleared except on regular files. As these cases arise, 

3272 the system implementors will have to determine whether these features enable 

3273 any security loopholes and specify appropriate restrictions. If the implementation 

3274 supports executing any file types other than regular files, the S_ISUID and 

3275 S_ISGID bits should be cleared for those file types in the same way as they are on 

3276 regular files. 

3277 B. 5.6.6 Set File Access and Modification Times 

3278 The actime structure member must be present so that an application may set it, 

3279 even though an implementation may ignore it and not change the access time on 

3280 the file. If an application intends to leave one of the times of a file unchanged 

3281 while changing the other, it should use stat( ) to retrieve the file’s stjatime and 

3282 stjntime parameters, set actime and modtime in the buffer, and change one of 

3283 them before making the utimeO call. 

3284 B.5.7 Configurable Pathname Variables 

3285 When the run-time facility described in B.4.8 was designed, it was realized that 

3286 some variables change depending on the file system. For example, it is quite 

3287 feasible for a system to have two varieties of file systems mounted: a System V | 

3288 file system and a BSD ‘Tast File System.” | 

3289 If limited to strictly compile-time features, no application that was widely distri- 

3290 buted in executable binary form could rely on more than 14 bytes in a pathname 

3291 component, as that is the minimum published for (NAME_MAX) in POSIX. 1. The 

3292 pathconfO function allows the application to take advantage of the most liberal 

3293 file system available at run-time. In many BSD-based systems, 255 bytes are | 

3294 allowed for pathname components. 
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3295 These values are potentially changeable at the directory level, not just at the file 

3296 system. And, unlike the overall system variables, there is no guarantee that 

3297 these might not change during program execution. 

3298 B.5.7.1 Get Configurable Pathname Variables 

i 3299 The pathconfO function was proposed immediately after the sysconfX) function 

3300 when it was realized that some configurable values may differ across file system, 

3301 directory, or device boundaries. 

3302 For example, [NAME_MAX] frequently changes between System V and BSD-based 

3303 file systems; System V uses a maximum of 14, BSD 255. On an implementation 

3304 that provided both types of file systems, an application would be forced to limit all 

3305 pathname components to 14 bytes, as this would be the value specified in 

3306 <limits . h> on such a system. 

3307 Therefore, various useful values can be queried on any pathname or file descrip- 

3308 tor, assuming that the appropriate permissions are in place. 

3309 The value returned for the variable (PATH_MAX) indicates the longest relative 

3310 pathname that could be given if the specified directory is the process’s current 

3311 working directory. A process may not always be able to generate a name that 

3312 long and use it if a subdirectory in the pathname crosses into a more restrictive 

3313 file system. 

3314 The value returned for the variable LPOSIX_CHOWN_RESTRICTED) also applies 

3315 to directories that do not have file systems mounted on them. The value may 

3316 change when crossing a mount point, so applications that need to know should 
8317 check for each directory. [An even easier check is to try the chown () function and 

3318 look for an error in case it happens.] 

3319 Unlike the values returned by sysconfO, the pathname-oriented variables are 

3320 potentially more volatile and are not guaranteed to remain constant throughout 

3321 the process’s lifetime. For example, in between two calls to pathconfO, the file 

3322 system in question may have been unmounted and remounted with different 

3323 characteristics. 

3324 Also note that most of the errors are optional. If one of the variables always has 

3325 the same value on an implementation, the implementation need not look at path 

3326 or fildes to return that value and is, therefore, not required to detect any of the 

3327 errors except the meaning of [EINVAL] that indicates that the value of name is not 

3328 valid for that variable. 

3329 If the value of any of the limits described in 2.8.4 or 2.8.5 are indeterminate (logi- 

3330 cally infinite), they will not be defined in <limits.h> and the pathconfO and 

3331 fpathconfO functions will return -1 without changing errno. This can be dis- 

3332 tinguished from the case of giving an unrecognized name argument because errno 

3333 will be set to [EINVAL] in this case. 

3334 Since -1 is a valid return value for the pathconfO and fpathconfO functions, 

3335 applications should set errno to zero before calling them and check errno only if 

3336 the return value is -1. 
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System III and System V have included a flag, O.NDELAY, to mark file descrip- 
tors so that user processes would not block when doing I/O to them. If the flag is 
set, a read() or write () call that would otherwise need to block for data returns a 
value of zero instead. But a read() call also returns a value of zero on end-of-file, 
and applications have no way to distinguish between these two conditions. 

BSD systems support a similar feature through a flag with the same name, but 
somewhat different semantics. The flag applies to all users of a file (or socket) 
rather than only to those sharing a file descriptor. The BSD interface provides a 
solution to the problem of distinguishing between a blocking condition and an 
end-of-file condition by returning an error, [EWOULDBLOCK], on a blocking 
condition. 

The 1984 /usr /group Standard (B59) includes an interface with some features 
from both System III/V and BSD. The overall semantics are that it applies only to | 
a file descriptor. However, the return indication for a blocking condition is an 
error, IE AG AIN I. This was the starting point for POSIX.l. 

The problem with the 1984 /usr /group Standard (B59) is that it does not allow 
compatibility with existing applications. An implementation cannot both conform 
to that standard and support applications written for existing System V or BSD | 
systems. Several changes have been considered address this issue. These 
include: 

(1) No change (from 1984 /usr /group Standard (B59)) 

(2) Changing to System III/V semantics 

(3) Changing to BSD semantics 

(4) Broadening POSIX.l to allow conforming implementation a choice among 
these semantics 

(5) Changing the name of the flag from 0_NDELAY 

(6) Changing to System III/V semantics and providing a new call to distin- 
guish between blocking and end-of-file conditions 

Alternative (5) was the consensus choice. The new name is 0_NONBLOCK. This | 
alternative allows a conforming implementation to provide backward compatibil- 
ity at the source and/or object level with either System III/V or BSD systems (but | 
POSIX. 1 does not require or even suggest that this be done). It also allows a Con- 
forming POSIX. 1 Application Using Extensions the functionality to distinguish 
between blocking and end-of-file conditions, and to do so in as simple a manner as 
any of the alternatives. The greatest shortcoming was that it forces all existing | 
System III/V and BSD applications that use this facility to be modified in order to | 
strictly conform to POSIX.l. This same shortcoming applies to (1) and (4) as well, 
and it applies to one group of applications for (2), (3), and (6). 

Systems may choose to implement both 0_NDELAY and 0_N0NBL0CK, and there 
is no conflict as long as an application does not turn both flags on at the same 
time. 
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3379 See also the discussion of scope in B. 6 . 5 . 1 . 


3380 B.6.1 Pipes 

3381 An implementation that fails write{) operations on fildes[0] or read() s on fildes[ 1] 

3382 is not required. Historical implementations (Version 7 and System V) return the 

3383 error [EBADF] in such cases. This allows implementations to set up a second pipe 

3384 for full duplex operation at the same time. A conforming application that uses the 
3386 pipe () function as described in POSIX. 1 will succeed whether this second pipe is 
3386 present or not. 


3387 B.6.1. 1 Create an Inter-Process Channel 

3388 The wording carefully avoids using the verb M to open” in order to avoid any impli- 

3389 cation of use of open (). 

3390 See also B.6.4.2. 





3391 B.6. 2 File Descriptor Manipulation 

3392 B.6. 2.1 Duplicate an Open File Descriptor 

3393 The dup () and dup2( ) functions are redundant. Their services are also provided 

3394 by the fcntlQ function. They have been included in POSIX 1 primarily for histori- 
3396 cal reasons, since many existing applications use them. 

3396 While the brief code segment shown is very similar in behavior to dup2(), a con- 

3397 forming implementation based on other functions defined by POSIX.l is 

3398 significantly more complex. Least obvious is the possible efTect of a signal- 

3399 catching function that could be invoked between steps and allocate or deallocate 

3400 file descriptors. This could be avoided by blocking signals. 

3401 The dup2() function is not marked obsolescent because it presents a type-safe ver- 

3402 sion of functionality provided in a type-unsafe version by fcnttt) . It is used in the 

3403 current draft of the Ada binding to POSIX 1 . 

3404 The dup2() function is not intended for use in critical regions as a synchroniza- 
3406 tion mechanism. 

3406 In the description of [EBADF], the case of fildes being out of range is covered by 

3407 the given case of fildes not being valid. The descriptions for fildes and fildes2 are 

3408 different because the only kind of invalidity that is relevant for fildes2 is whether 

3409 it is out of range; that is, it does not matter whether fildes2 refers to an open file 

3410 when the dup2() call is made. 

3411 If fildes2 is a valid file descriptor, it shall be closed, regardless of whether the 

3412 function returns an indication of success or failure, unless fildes2 is equal to 

3413 fildes. 
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3414 B.6.3 File Descriptor Deassignment 

3415 B.6.3. 1 Close a File 

3416 Once a file is closed, the file descriptor no longer exists, since the integer 

3417 corresponding to it no longer refers to a file. 

3418 The use of interruptible device close routines should be discouraged to avoid prob- 

3419 lems with the implicit closes of file descriptors by exec and exit(). POSIX. 1 only 

3420 intends to permit such behavior by specifying the [EINTR] error case. 

3421 B.6.4 Input and Output 

3422 

3423 

3424 

3425 

3426 

3427 
34 28 
3*129 

3430 

3431 
34 32 

3433 

3434 

> t 3435 

3436 

3437 
34 38 

3439 

3440 

3441 

3442 

3443 

3444 

3445 

3446 In 4.3BSD, a readO or writeO that is interrupted by a signal before transferring 

3447 any data does not by default return an [EINTR] error, but is restarted. In 4.2BSD, 

3148 4.3BSD, and the Eighth Edition there is an additional function, select (), whose 

3449 purpose is to pause until specified activity (data to read, space to write, etc.) is 

3450 detected on specified file descriptors. It is common in applications written for 

3451 those systems for selectO to be used before readO in situations (such as keyboard 

3452 input) where interruption of I/O due to a signal is desired. But this approach does 

3453 not conform, because selectO is not in POSIX. 1. 4.3BSD semantics can be provided 

3454 by extensions to POSIX. 1. 

3455 POSIX.1 permits readO and writeQ to return the number of bytes successfully 

3456 transferred when interrupted by an error. This is not simply required because it 


The use of I/O with large byte counts has always presented problems. Ideas such | 
as Iread ( ) and Iwritei ) (using and returning longs ) were considered at one time. | 
The current solution is to use abstract types on the C Standard (2) interface to | 
read ( ) and write 0 (and not to discuss common usage). The abstract types can be | 
declared so that existing interfaces work, but can also be declared so that larger | 
types can be represented in future implementations. It is presumed that what- | 
ever constraints limit the maximum range of size_t also limit portable I/O requests | 
to the same range. POSIX.1 also limits the range further by requiring that the | 
byte count be limited so that a signed return value remains meaningful. Since | 
the return type is also a (signed) abstract type, the byte count can be defined by | 
the implementation to be larger than an int can hold. I 

POSIX.1 requires that no action be taken when nbyte is zero. This is not intended 
to take precedence over detection of errors (such as invalid buffer pointers or file 
descriptors). This is consistent with the rest of POSIX.1, but the phrasing here 
could be misread to require detection of the zero case before any other errors. A 
value of zero is to be considered a correct value, for which the semantics are a 
no-op. 

There were recommendations to add format parameters to read( ) and write 0 in 
order to handle networked transfers among heterogeneous file system and base 
hardware types. Such a facility may be required for support by the OSI presenta- 
tion of layer services. However, it was determined that this should correspond | 
with similar C Language facilities, and that is beyond the scope of POSIX.1. The | 
concept was suggested to the developers of the C Standard {2} for their considera- | 
tion as a possible area for future work. 
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3467 was not done by Version 7, System III, or System V, and because some hardware 

3468 may not be capable of returning information about partial transfers if a device 

3469 operation is interrupted. Unfortunately, this does make writing a Conforming 

3460 POSIX.1 Application more difficult in circumstances where this could occur. 

3461 Requiring this behavior does not address the situation of pipelined buffers, such 

3462 as might be found in streaming tape drives or other devices that read ahead of the 

3463 actual requests. The signal interruption will often indicate an exceptional condi- 

3464 tion and flush all buffers. Thus, the amount read from the device may be dif- 

3465 ferent from the amount transferred to the application. 

3466 The issue of which files or file types are interruptible is considered an implemen- 

3467 tation design issue. This is often affected primarily by hardware and reliability 

3468 issues. 

3469 There are no references to actions taken following an “unrecoverable error.” It is 

3470 considered beyond the scope of POSIX.1 to describe what happens in the case of 

3471 hardware errors. 


3472 B.6.4. 1 Read from a File 

3473 POSIX.1 does not specify the value of the file offset after an error is returned; 

3474 there are too many cases. For programming errors, such as [EBADF], the concept 
3476 is meaningless since no file is involved. For errors that are detected immediately, 

3476 such as [EAGAIN], clearly the pointer should not change. After an interrupt or 

3477 hardware error, however, an updated value would be very useful and is the 

3478 behavior of many implementations. 

3479 Note that a readO of zero bytes does not modify stjatime. A readO that requests 

3480 more than zero bytes, but returns zero, does modify st_atime . 

3481 B.6.4.2 Write to a File 

3482 An attempt to write to a pipe or FIFO has several mqjor characteristics: 

3483 Atomic/nonatomic 

3484 A write is atomic if the whole amount written in one operation is not 

3485 interleaved with data from any other process. This is useful when there 

3486 are multiple writers sending data to a single reader. Applications need 

3487 to know how large a write request can be expected to be performed atomi- 

3488 cally. This maximum is called (PIPEJBUF). POSIX.1 does not say 

3489 whether write requests for more than (PIPEJBUF) bytes will be atomic, 

3490 but requires that writes of {PIPE_BUF} or fewer bytes shall be atomic. 

3491 Blocking/immediate 

3492 Blocking is only possible with 0_N0NBL0CK clear. If there is enough 

3493 space for all the data requested to be written immediately, the implemen- 

3*194 tation should do so. Otherwise, the process may block; that is, pause 

3495 until enough space is available for writing. The effective size of a pipe or 

3496 FIFO (the maximum amount that can be written in one operation without 

3497 blocking) may vary dynamically, depending on the implementation, so it 

3498 is not possible to specify a fixed value for it. 
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Complete/partial/deferred 
A write request, 

int fildea; 
size_t nbyte; 
ssize_t ret; 
char *buf; 

ret - write (fildes, buf, nbyte); 
may return 

complete: ret = nbyte 
partial: ret < nbyte 

This shall never happen if nbyte <, {PIPE_BUF}. If it does 
happen (with nbyte > (PIPE_BUF)), POSIX.1 does not 
guarantee atomicity, even if ret 2s [PIPE.BUF], because 
atomicity is guaranteed according to the amount requested , 
not the amount written. 

deferred: ret = -1, errno - [EAGAIN] 

This error indicates that a later request may succeed. It 
does not indicate that it shall succeed, even if nbyte ^ 
{PIPE_BUF}, because if no process reads from the pipe or 
FIFO, the write will never succeed. An application could 
usefully count the number of times [EAGAIN] is caused by a 
particular value of nbyte > [PIPE.BUF] and perhaps do 
later writes with a smaller value, on the assumption that 
the effective size of the pipe may have decreased. 

Partial and deferred writes are only possible with 0_NONBLOCK set. 

The relations of these properties are shown in the following tables. 


Write to a Pipe or FIFO with O.NONBLOCK clear 

Immediately 

Writable: 

None 

Some 

nbyte 


Atomic 

Atomic 

Atomic 

nbyte 

blocking 

blocking 

immediate 

(P1PE_BUF) 

nbyte 

nbyte 

nbyte 

nbyte > 

Blocking 

Blocking 

Blocking 

(PIPE_BUF) 

nbyte 

nbyte 

nbyte 


If the O.NONBLOCK flag is clear, a write request shall block if the amount writ- 
able immediately is less than that requested. If the flag is set [by fcntli)), a write 
request shall never block. 
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3537 

3538 
3639 

3540 

3541 

3542 

3543 

3544 


3545 There is no exception regarding partial writes when 0_N0NBL0CK is set. With | 

3546 the exception of writing to an empty pipe, POSIX .1 does not specify exactly when a 

3547 partial write will be performed sinbe that would require specifying internal 

3548 details of the implementation. Every application should be prepared to handle 

3549 partial writes when 0_NONBLOCK is set and the requested amount is greater 

3550 than (PIPE_BUF1, just as every application should be prepared to handle partial 

3561 writes on other kinds of file descriptors. 

3552 The intent of forcing writing at least one byte if any can be written is to assure | 

3553 that each write will make progress if there is any room in the pipe. If the pipe is | 

3554 empty, (PIPE_BUF) bytes must be written; if not, at least some progress must | 

3556 have been made. I 

3556 Where POSIX.1 requires -1 to be returned and errno set to [EAGAIN], most histori- 

3567 cal implementations return zero (with the O.NDELAY flag set — that flag is the 

3558 historical predecessor of O.NONBLOCK, but is not itself in POSIX.1). The error 

3659 indications in POSIX.1 were chosen so that an application can distinguish these 

3560 cases from end-of-file. While write () cannot receive an indication of end-of-file, 

3561 readi) can, and the two functions have similar return values. Also, some existing | 

3662 systems (e.g., Eighth Edition) permit a write of zero bytes to mean that the reader 

3563 should get an end-of-file indication; for those systems, a return value of zero from 

3564 write () indicates a successful write of an end-of-file indication. 

3565 The concept of a (PIPE.MAX) limit (indicating the maximum number of bytes that 

3566 can be written to a pipe in a -single operation) was considered, but rejected, | 

3567 because this concept would unnecessarily limit application writing. ! 

3568 See also the discussion of O.NONBLOCK in B.6. 

3569 Writes can be serialized with respect to other reads and writes. If a readi) of file | 

3570 data can be proven (by any means) to occur after a writei) of the data, it must 1 

1 3571 reflect that writei), even if the calls are made by different processes. A similar | 

3672 requirement applies to multiple write operations to the same file position. This is | 

3673 needed to guarantee the propagation of data from writei) calls to subsequent | 

3574 readi) calls. This requirement is particularly significant for networked file sys- | 

3576 terns, where some caching schemes violate these semantics. 

3576 Note that this is specified in terms of readi) and writei). Additional calls such as | 

3577 the common readvi) and writev () would want to obey these semantics. A new | 

3578 “high-performance” write analog that did not follow these serialization require- | 

3579 ments would also be permitted by this wording. POSIX.1 is also silent about any | 

3580 effects of application-level caching (such as that done by stdio). I 


Write to a Pipe or FIFO with O.NONBLOCK set 


Immediately 

Writable: 

None 

Some 

nbyte 

nbyte <. 

-1, 

-i. 

Atomic 

(PIPE_BUF) 

[EAGAIN] 

[EAGAIN] 

nbyte 



< nbyte 

< nbyte 

nbyte > 

- 1 , 

or -1, 

or-1, 

(PIPE_BUF) 

[EAGAIN] 

[EAGAIN] 

[ EAGAIN 1 
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3681 POSIX.1 does not specify the value of the file offset after an error is returned; 

3682 there are too many cases. For programming errors, such as [EBADF], the concept 

3683 is meaningless since no file is involved. For errors that are detected immediately, 

3684 such as [EAGAINJ, clearly the pointer should not change. After an interrupt or 
3686 hardware error, however, an updated value would be very useful and is the 
3586 behavior of many implementations. 


3687 POSIX. 1 does not specify behavior of concurrent writes to a file from multiple 
3588 processes. Applications should use some form of concurrency control. 



3589 B.6.5 Control Operations on Files 

3590 B.6.5.1 Data Definitions for File Control Operations 

3591 The main distinction between the file descriptor flags and the file status flags is 

3592 scope. The former apply to a single file descriptor only, while the latter apply to 

3593 all file descriptors that share a common open file description [by inheritance 
3694 through fork() or an FJDUPFD operation with fcntl()]. For 0_N0NBL0CK, this 

3595 scoping is like that of 0_NDELAY in System V rather than in 4.3BSD, where the 

3596 scoping for 0_NDELAY is different from all the other flags accessed via the same 

3597 commands. 

3598 For example: 

3699 fdl = open (pathname, oflags) ; 

3600 fd2 = dup (fdl) ; 

3601 fd3 = open (pathname, oflags) ; 

3602 Does an fcntl{) call on fdl also apply to fd2 or fd3 or to both? According to 

3603 POSIX.l, F_SETFD applies only to fdl, while F_SETFL applies to fdl and fd2 but 

3604 not to fd3. This is in agreement with all common historical implementations 

3605 except for BSD with the F.SETFL command and the 0_NDELAY flag (which would 

3606 apply to fd3 as well). Note that this does not force any incompatibilities in BSD 

3607 implementations, because O.NDELAY is not in POSIX.l. See also B.6. 

3608 Historically, the file descriptor flags have had only the literal values 0 and 1. 

3609 POSIX. 1 defines the symbolic name FD.CLOEXEC to permit a more graceful exten- 

3610 sion of this functionality. Owners of existing applications should be aware of the 

3611 need to change applications using the literal values, and implementors should be 

3612 aware of the existence of this practice in existing applications. 

3613 B.6.5.2 File Control 

36H The ellipsis in the Synopsis is the syntax specified by the C Standard {2} for a 

3615 variable number of arguments. It is used because System V uses pointers for the 

3616 implementation of file locking functions. 

sen The arg values to F.GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag 

3618 values to allow for future growth. Applications using these functions should do a 

3619 read-modify- write operation on them, rather than assuming that only the values 

3620 defined by POSIX.l are valid. It is a common error to forget this, particularly in 

3621 the case of F_SETFD, because there is only one flag in POSIX.l. 
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3622 POSIX. 1 permits concurrent read and write access to file data using the fcntlO 

3623 function; this is a change from the 1984 /usr/ group Standard (B59) and early 

3624 POSIX.1 drafts, which included a lockf\) function. Without concurrency controls, 

3625 this feature may not be fully utilized without occasional loss of data. Since other 

3626 mechanisms for creating critical regions, such as semaphores, are not included, a 

3627 file record locking mechanism was thought to be appropriate. The fcntl() mechan- 
i 3628 ism may be used to implement semaphores, although access is not first-in-first- 

3629 out without extra application development effort. 

3630 Data losses occur in several ways. One is that read and write operations are not 

3631 atomic, and as such a reader may get segments of new and old data if con- 

3632 currently written by another process*. Another occurs when several processes try 

3633 to update the same record, without sequencing controls; several updates may 

3634 occur in parallel and the last writer will “win.” Another case is a b-tree or other 
3636 internal list-based database that is undergoing reorganization. Without exclusive 

3636 use to the tree segment by the. updating process, other reading processes chance 

3637 getting lost in the database when the index blocks are split, condensed, inserted, 

3638 or deleted. While fcntl() is useful for many applications, it is not intended to be 

3639 overly general and will not handle the b-tree example well. 

3640 This facility is only required for regular files because it is not appropriate for 

3641 many devices such as terminals and network connections. 

3642 Since fcntl() works with “any file descriptor associated with that file, however it is 

3643 obtained,” the file descriptor may have been inherited through a forki) or exec 

3644 operation and thus may affect a file that another process also has open. 

3646 The use of the open file description to identify what to lock requires extra calls 

3646 and presents problems if several processes are sharing an open file description, 

3647 but there are too many implementations of the existing mechanism for POSIX.1 to 

3648 use different specifications. 

3649 Another consequence of this model is that closing any file descriptor for a given | 

3650 file (whether or not it is the same open file description that created the lock) | 

3661 causes the locks on that file to be relinquished for that process. Equivalently, any | 

3662 close for any file/process pair relinquishes the locks owned on that file for that | 

3663 process. But note that while an open file description may be shared through 

3664 fork(), locks are not inherited through fork() . Yet locks may be inherited through 
3666 one of the exec functions. 

3666 The identification of a machine in a network environment is outside of the scope 
3657 of POSIX.l. Thus, an Ijsysid member, such as found in System V, is not included 
3668 in the locking structure. 

3659 Since locking is performed with fcntl(), rather than lockfX), this specification 

3660 prohibits use of advisory exclusive locking on a file that is not open for writing. 

3661 Before successful return from a F_SETLK or F_SETLKW request, the previous lock 

3662 type for each byte in the specified region shall be replaced by the new lock type. 

3663 This can result in a previously locked region being split into smaller regions. If 

3664 this would cause the number of regions being held by all processes in the system 

3665 to exceed a system-imposed limit, the fcntl( ) function returns —1 with errno set to 

3666 IENOLCK]. 
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Mandatory locking was a m?\jor feature of the 1984 /usr/ group Standard (B59). 
For advisory file record locking to be effective, all processes that have access to a 
file must cooperate and use the advisory mechanism before doing I/O on the file. 
Enforcement-mode record locking is important when it cannot be assumed that all 
processes are cooperating. For example, if one user uses an editor to update a file 
at the same time that a second user executes another process that updates the 
same file and if only one of the two processes is using advisory locking, the 
processes are not cooperating. Enforcement-mode record locking would protect 
against accidental collisions. 

Secondly, advisory record locking requires a process using locking to bracket each 
I/O operation with lock (or test) and unlock operations. With enforcement-mode 
file and record locking, a process can lock the file once and unlock when all I/O 
operations have been completed. Enforcement-mode record locking provides a 
base that can be enhanced, for example, with sharable locks. That is, the 
mechanism could be enhanced to allow a process to lock a file so other processes 
could read it, but none of them could write it. 

Mandatory locks were omitted for several reasons: 

(1) Mandatory lock setting was done by multiplexing the set-group-ID bit in 
most implementations; this was confusing, at best. 

(2) The relationship to file truncation as supported in 4.2BSD was not well 
specified. 

(3) Any publicly readable file could be locked by anyone. Many historical 
implementations keep the password database in a publicly readable file. 
A malicious user could thus prohibit logins. Another possibility would be 
to hold open a long-distance telephone line. 

(4) Some demand-paged historical implementations offer memory mapped 
files, and enforcement cannot be done on that type of file. 

Since sleeping on a region is interrupted with any signal, alarmi) may be used to 
provide a timeout facility in applications requiring it. This is useful in deadlock 
detection. Because implementation of full deadlock detection is not always feasi- 
ble, the 1EDEADLK] error was made optional. 


B.6.5.3 Reposition Read/Write File Offset 

The C Standard {2} includes the functions fgetposi) and fsetposO, which work on 
very large files by use of a special positioning type. 

Although Iseek () may position the file offset beyond the end of the file, this func- 
tion does not itself extend the size of the file. While the only function in POSIX. 1 
that may extend the size of the file is write (), several C Standard {2} functions, 
such as fwritei), fprintfi), etc., may do so [by causing calls on writei)]. 

An invalid file offset that would cause [EINVAL] to be returned may be both 
implementation defined and device dependent (for example, memory may have 
few invalid values). A negative file offset may be valid for some devices in some 
implementations. 


37io See B. 6.5.2 for a explanation of the use of signed and unsigned offsets with 
37U Iseek (). 


3712 B.7 Device- and Class-Specific Functions 

3713 There were several sources of difficulties involved with using historical interfaces 

3714 as the basis of this section: 

3715 (1) The basic Version 7 ioctli ) mechanism is difficult to specify adequately, 

3716 due to its use of a third argument that varies in both size and type 

3717 according to the second, command, argument. 

3718 (2) System III introduced and System V continued ioctli) commands that are 

3719 completely different from those of Version 7. 

3720 (3) 4.2BSD and other BSD systems added to the basic Version 7 ioctli) com- j 

3721 mand set; some of these were for features such as job control that 

3722 POSIX. 1 eventually adopted. 

3723 (4) None of the basic historical implementations are adequate in an intema- 

3724 tional environment. This concern is not technically within the scope of 

3725 POSIX. 1, but the goal of POSIX.l was to mandate no unnecessary impedi- | 

3726 ments to internationalization. | 

3727 The 1984 /usr /group Standard (B59) attempted to specify a portable mechanism 

( 3728 that application writers could use to get and set the modes of an asynchronous 

3729 terminal. The intention of that committee was to provide an interface that was 

3730 neither implementation specific nor hardware dependent. Initial proposals dealt 

3731 with high-level routines similar to the curses library (available on most historical 

3732 implementations). In such an implementation, the user interface would consist of 

3733 calls similar to: • 

3734 setrawO ; 

3735 setcookedf); 

3736 It was quickly pointed out that if such routines were standardized, the definition 

3737 of raw and cooked” would have to be provided. If these modes were not well 

3738 defined in POSIX.l, application code could not be written in a portable way. How- 

3739 ever, the definition of the terms would force low-level concepts to be included in a 

3740 supposedly high-level interface definition. 

3741 Focus was given to the necessary low-level attributes that were needed to support | 

3742 the necessary terminal characteristics (e.g., line speeds, raw mode, cooked mode, 

3743 etc.). After considerable debate, a structure similar to, but more flexible than, the | 

3744 System III termio was accepted. The format of that structure, referred to as the | 

3745 termios structure, has formed the basis for the current section. 

3746 A method was needed to communicate with the system about the termios informa- 
3^47 tion. Proposals included: 

3748 (1) The ioctli) function as in System V. This had the same problems as men- 

3749 tioned previously for the Version 7 ioctli ) function and was basically 

3750 identical to it. Another problem was that the direction of the command 

3751 (whether information is written from or read into the third argument) 
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was not specified— in historical implementations, only the device driver 
knows this information. This was a problem for networked implementa- 
tions. It was also a problem that there was no size parameter to specify 
the variable size of the third argument, and there was a similar problem 
with its type. 

(2) An iocntU ) function with additional arguments specifying direction, type, 
and size. But these new arguments did not help application writers, who 
would have no control over their values, which would have to match each 
command exactly. The new arguments did, however, solve the problems 
of networked implementations. And iocntli) would have been implement- 
able in terms of ioctli) on historical implementations (without need for 
modifying existing code), although it would have been easy to update 
existing code to use the arguments directly. 

(3) A termcntlO function with the same arguments as proposed for the 
iocntli) function. The difference was that termcntlO would be limited to 
terminal interface functions; there would be other interface functions, 
such as a tapecntli ) function for tape interfaces, rather than a single gen- 
eral device interface routine. 

(4) Unspecified functions. The issue of what the interface function(s) should 
be called was avoided for many of the early drafts while details of the | 
information to be handled was of prime concern. The resulting | 
specification resembled the information in System V, but attempted to 
avoid problems of case, speed, networks, and internationalization. 

Specific tc+i) functions 3 ' to replace each ioctli) function were finally incorporated 
into POSIX. 1, instead of any of the previously mentioned proposals. 

The issue of modem control was excluded from POSIX.l on the grounds that 


3778 

3779 

3780 

3781 

3782 


It was concerned with setting and control of hardware timers. 

The appropriate timers and settings vary widely internationally. 

Feedback from European computer manufacturers indicated that this | 
facility was not consistent with European needs and that specification of | 
such a facility was not a requirement for portability. I 


3783 B.7.1 General Terminal Interface 

3784 If the implementation does not support this interface on any device types, it 

3785 should behave as if it were being used on a device that is not a terminal device (in 

3786 most cases errno will be set to [ENOTTY]) on return from functions defined by this 

3787 interface. This is based on the fact that many applications are written to run 

3788 both interactively and in some noninteractive mode, and they adapt themselves at 

3789 run time. Requiring that they all be modified to test an environment variable to 


3790 3) The notation /c*() is reminiscent of shell pattern matching notation and is an abbreviated way of 

3791 referring to all functions beginning with the letters “tc.” 
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3792 determine if they should try to adapt is unnecessary. On a system that provides 

3793 no Section 7 interface, providing all the entry points as stubs that return 

3794 [ENOTTY] (or an equivalent, as appropriate) has the same effect and requires no 

3795 changes to the application. 

3796 Although the needs of both interface implementors and application developers 

3797 were addressed throughout POSIX.l, this section pays more attention to the needs 

3798 of the latter. This is because, while many aspects of the programming interface 

3799 can be hidden from the user by the application developer, the terminal interface is 

3800 usually a large part of the user interface. Although to some extent the application 

3801 developer can build missing features or work around inappropriate ones, the 

3802 difficulties of doing that are greater in the terminal interface than elsewhere. For 

3803 example, efficiency prohibits the average program from interpreting every charac- 

3804 ter passing through it in order to simulate character erase, line kill, etc. These 

3805 functions should usually be done by the operating system, possibly at the inter- 

3806 rupt level. 

3807 The £c*() functions were introduced as a way of avoiding the problems inherent in 

3808 the traditional ioctli) function and in variants of it that were proposed. For exam- 

3809 pie, tcsetattri) is specified in place of the use of the TCSETA ioctli) command func- 

38 10 tion. This allows specification of all the arguments in a manner consistent with 

3811 the C Standard (2), unlike the varying third argument of ioctli), which is some- 

3812 times a pointer (to any of many different types) and sometimes an int. 

3813 The advantages of this new method include: 

3814 — It allows strict type checking. 

3816 — The direction of transfer of control data is explicit. 

3816 — Portable capabilities are clearly identified. 

3817 — The need for a general interface routine is avoided. 

3818 — Size of the argument is well-defined (there is only one type). 

3819 The disadvantages include: 

3820 — No historical implementation uses the new method. 

3821 — There are many small routines instead of one general-purpose one. 

3822 — The historical parallel with fcntli) is broken. 

3823 B.7.1.1 Interface Characteristics 

3824 B.7.1. 1.1 Opening a Terminal Device File 

3825 Further implications of the effects of CLOCAL are discussed in 7. 1.2.4. 

3826 B.7.1. 1.2 Process Groups 

3827 There is a potential race when the members of the foreground process group on a 

3828 terminal leave that process group, either by exit or by changing process groups. 

3829 After the last process exits the process group, but before the foreground process 

3830 group ID of the terminal is changed (usually by a job-control shell), it would be 

3831 possible for a new process to be created with its process ID equal to the terminal’s 
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3832 foreground process group ID. That process might then become the process group | 

3833 leader and accidentally be placed into the foreground on a terminal that was not | 

3834 necessarily its controlling terminal. As a result of this problem, the controlling | 

3835 terminal is defined to not have a foreground process group during this time. | 

3836 The cases where a controlling terminal has no foreground process group occur | 

3837 when all processes in the foreground process group either terminate and are | 

3838 waited for or join other process groups via setpgidi) or setsidi) . If the process | 

3839 group leader terminates, this is the first case described; if it leaves the process | 

3840 group via setpgidi), this is the second case described [a process group leader can- | 

3841 not successfully call setsidOh When one of those cases causes a controlling termi- | 

3842 nal to have no foreground process group, it has two visible effects on applications. | 

3843 The first is the value returned by tcgetpgrp (), as discussed in 7.2.3 and B.7.2.3. | 

3844 The second (which occurs only in the case where the process group leader ter- | 

3845 minates) is the sending of signals in response to special input characters. The | 

3846 intent of POSIX.l is that no process group be wrongly identified as the foreground | 

3847 process group by tcgetpgrp () or unintentionally receive signals because of place- | 

3848 ment into the foreground. | 

3849 In 4.3BSD, the old process group ID continues to be used to identify the fore- | 

3850 ground process group and is returned by the function equivalent to tcgetpgrp (). | 

3851 In that implementation it is possible for a newly created process to be assigned | 

3852 the same value as a process ID and then form a new process group with the same | 

3853 value as a process group ID. The result is that the new process group would | 

3854 receive signals from this terminal for no apparent reason, and POSIX.l precludes [ 

3855 this by forbidding a process group from entering the foreground in this way. It | 

3856 would be more direct to place part of the requirement made by the last sentence | 

3857 under 3.1.1, but there is no convenient way for that subclause to refer to the value | 

3858 that tcgetpgrp () returns, since in this case there is no process group and thus no | 

3859 process group ID. | 

3860 One possibility for a conforming implementation is to behave similarly to 4.3BSD, | 

3861 but to prevent this reuse of the ID, probably in the implementation of fork(), as | 

3862 long as it is in use by the terminal. | 

3863 Another possibility is to recognize when the last process stops using the | 

3864 terminal’s foreground process group ID, which is when the process group lifetime | 

3865 ends, and to change the terminal’s foreground process group ID to a reserved | 

3866 value that is never used as a process ID or process group ID. (See the definition of | 

3867 process group lifetime in 2.2.2.) The process ID can then be reserved until the ter- | 

3868 minal has another foreground process group. | 

3869 The 4.3BSD implementation permits the leader (and only member) of the fore- | 

3870 ground process group to leave the process group by calling the equivalent of | 

3871 setpgidi) and to later return, expecting to return to the foreground. There are no | 

3872 known application needs for this behavior, and POSIX.l neither requires nor for- | 

3873 bids it (except that it is forbidden for session leaders) by leaving it unspecified. | 

3874 B.7.1.1.3 The Controlling Terminal 

3875 POSIX.1 does not specify a mechanism by which to allocate a controlling terminal. 

3876 This is normally done by a system utility (such as getty) and is considered an 

3877 administrative feature outside the scope of POSIX.l. 
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Historical implementations allocate controlling terminals on certain openi) calls. 
Since openi) is part of POSIX.1, its behavior had to be dealt with. The traditional | 
behavior is not required because it is not very straightforward or flexible for j 
either implementations or applications. However, because of its prevalence, it 
was not practical to disallow this behavior either. Thus, a mechanism was stand- 
ardized to ensure portable, predictable behavior in openi). 

Some historical implementations deallocate a controlling terminal on its last sys- | 
temwide close. This behavior in neither required nor prohibited. Even on imple- j 
mentations that do provide this behavior, applications generally cannot depend on | 
it due to its systemwide nature. | 

B.7.1.1.4 Terminal Access Control 

The access controls described in this subclause apply only to a process that is | 
accessing its controlling terminal. A process accessing a terminal that is not its 
controlling terminal is effectively treated the same as a member of the foreground 
process group. While this may seem unintuitive, note that these controls are for 
the purpose of job control, not security, and job control relates only to a process’s 
controlling terminal: Normal file access permissions handle security. 

If the process calling read () or writei) is in a background process group that is 
orphaned, it is not desirable to stop the process group, as it is no longer under the 
control of a job-control shell that could put it into foreground again. Accordingly, 
calls to readi) or writei) functions by such processes receive an immediate error 
return. This is different than in 4.2BSD, which kills orphaned processes that 
receive terminal stop signals. 

The foreground/background/orphaned process group check performed by the ter- 
minal driver must be repeatedly performed until the calling process moves into 
the foreground or until the process group of the calling process becomes orphaned. 
That is, when the terminal driver determines that the calling process is in the 
background and should receive a job-control signal, it sends the appropriate sig- 
nal (SIGTTIN or SIGTTOU) to^very process in the process group of the calling pro- 
cess and then it allows the calling process to immediately receive the signal. The 
latter is typically performed by blocking the process so that the signal is immedi- 
ately noticed. Note, however, that after the process finishes receiving the signal 
and control is returned to the driver, the terminal driver must reexecute the fore- 
ground/background/orphaned process group check. The process may still be in 
the background, either because it was continued in the background by a job- 
control shell, or because it caught the signal and did nothing. 

The terminal driver repeatedly performs the foreground/background/orphaned 
process group checks whenever a process is about to access the terminal. In the 
case of writei) or the control functions in 7.2, the check is performed at the entry 
of the function. In the case of readi), the check is performed not only at the entry 
of the function, but also after blocking the process to wait for input characters (if 
necessary). That is, once the driver has determined that the process calling the 
readi) function is in the foreground, it attempts to retrieve characters from the 
input queue. If the queue is empty, it blocks the process waiting for characters. 
When characters are available and control is returned to the driver, the terminal 
driver must return to the repeated foreground/background/orphaned process 
group check again. The process may have moved from the foreground to the 
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3925 background while it was blocked waiting for input characters. 

3926 B.7. 1.1.5 Input Processing and Reading Data 

3927 There is no additional rationale provided for this subclause. 

3928 B. 7. 1.1. 6 Canonical Mode Input Processing 

3929 The term "character” is intended here. ERASE should erase the last character, 

3930 not the last byte. In the case of multibyte characters, these two may be different. 

393 1 4 . 3 BSD has a WERASE character that erases the last “word” typed (but not any 

3932 preceding blanks or tabs). A word is defined as a sequence of nonblank charac- 

3933 ters, with tabs counted as blanks. Like ERASE, WERASE does not erase beyond 

3934 the beginning of the line. This WERASE feature has not been specified in POSIX.l 

3935 because it is difficult to define in the international environment. It is only useful 
39:16 for languages where words are delimited by blanks. In some ideographic 

3937 languages, such as Japanese and Chinese, words are not delimited at all. The 

3938 WERASE character should presumably take one back to the beginning of a sen- 

3939 tence in those cases; practically, this means it would not get much use for those 

3940 languages. 

3941 It should be noted that there is a possible inherent deadlock if the application and | 

3942 implementation conflict on the value of MAX_CANON. With ICANON set (if IXOFF j 

3943 is enabled) and more than MAX_CANON characters transmitted without a | 

3944 linefeed, transmission will be stopped, the linefeed (or carriage return when | 
3946 ICRLF is set) will never arrive, and the read ( ) will never be satisfied. 

3946 An application should not set IXOFF if it is using canonical mode unless it knows | 

3947 that (even in the face of a transmission error) the conditions described previously | 

3948 cannot be met or unless it is prepared to deal with the possible deadlock in some | 

3949 other way, such as timeouts. 

3950 It should also be noted that this can be made to happen in noncanonical mode if | 

3951 the trigger value for sending IXOFF is less than VMIN and VTIME is zero. i 

3952 B.7.1.1.7 Noncanonical Mode Input Processing 

3953 Some points to note about MIN and TIME: 

The interactions of MIN and TIME are not symmetric. For example, when | 
MIN > 0 and TIME = 0, TIME has no effect. However, in the opposite case 
where MIN = 0 and TIME > 0, both MIN and TIME play a role in that MIN 
is satisfied with the receipt of a single character. 

Also note that in case A (MIN > 0, TIME > 0), TIME represents an inter- 
character timer while in case C (MIN = 0, TIME > 0) TIME represents a 
read timer. 

3961 These two points highlight the dual purpose of the MIN/TIME feature. Cases A 

3962 and B, where MIN > 0, exist to handle burst-mode activity (e.g., file transfer pro- 

3963 grams) where a program would like to process at least MIN characters at a time. 

3964 In case A, the intercharacter timer is activated by a user as a safety measure; in 

3965 case B, it is turned off. 


3954 (1) 

3966 

3956 

3957 

3958 (2) 

3959 
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Cases C and D exist to handle single-character timed transfers. These cases are 
readily adaptable to screen-based applications that need to know if a character is 
present in the input queue before refreshing the screen. In case C the read is 
timed; in case D, it is not. 



Another important note is that MIN is always just a minimum. It does not denote 
a record length. That is, if a program does a read of 20 bytes, MIN is 10, and 25 
characters are present, 20 characters shall be returned to the user. In the special | 
case of MIN=0, this still applies: if more than one character is available, they all | 
will be returned immediately. j 

B.7.1.1.8 Writing Data and Output Processing 

There is no additional rationale provided for this subclause. 

B. 7.1. 1.9 Special Characters 

There is no additional rationale provided for this subclause. 

B. 7.1. 1.10 Modem Disconnect 

There is no additional rationale provided for this subclause. 

B.7.1.1.11 Closing a Terminal Device File 

POSIX. 1 is silent ori whether a close() will block on waiting for transmission to | 
drain, or even if a close ( ) might cause a flush of pending output. If the application | 
is concerned about this, it should call the appropriate function, such as tcdrain(), j 
to ensure the desired behavior. j 

B.7.1.2 Parameters That Can Be Set | 

B.7.1.2.1 termios Structure 

This structure is part of an interface that, in general, retains the historic group- 
ing of flags. Although a more optimal structure for implementations may be pos- 
sible, the degree of change to applications would be significantly larger. 

B.7.1.2.2 Input Modes 

Some historical implementations treated a long break as multiple events, as 
many as one per character time. The wording in POSIX. 1 explicitly prohibits this. 

Although the ISTRIP flag is normally superfluous with today’s terminal hardware 
and software, it is historically supported. Therefore, applications may be using 
ISTRIP, and there is no technical problem with supporting this flag. Also, applica- 
tions may wish to receive only 7-bit input bytes and may not be connected directly 
to the hardware terminal device (for example, when a connection traverses a 
network). 

Also, there is no requirement in general that the terminal device ensures that 
high-order bits beyond the specified character size are cleared. ISTRIP provides 
this function for 7-bit characters, which are common. 
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4003 In dealing with multibyte characters, the consequences of a parity error in such a 

4004 character, or in an escape sequence affecting the current character set, are beyond 

4005 the scope of POSIX. 1 and are best dealt with by the application processing the 

4006 multibyte characters. 

4007 B.7.1.2.3 Output Modes 

400H POSIX. 1 does not describe postprocessing of output to a terminal or detailed con- 

4009 trol of that from a portable application. (That is, translation of newline to car- 

4010 riage return followed by linefeed or tab processing.) There is nothing that a port- 

4011 able application should do to its output for a terminal because that would require 

4012 knowledge of the operation of the terminal. It is the responsibility of the operat- 

4013 ing system to provide postprocessing appropriate to the output device, whether it 

4014 is a terminal or some other type of device. 

4015 Extensions to POSIX. 1 to control the type of postprocessing already exist and are 

4016 expected to continue into the future. The control of these features is primarily to 

4017 adjust the interface between the system and the terminal device so the output 

4018 appears on the display correctly. This should be set up before use by any 

4019 application. 

4020 In general, both the input and output modes should not be set absolutely, but 

4021 rather modified from the inherited state. 

4022 B.7.1.2.4 Control Modes 

4023 This subclause could be misread that the symbol “CSIZE” is a title in Table 7-3. | 

4024 Although it does serve that function, it is also a required symbol, as a literal read- j 

4025 ing of POSIX . 1 (and the caveats about typography) would indicate. j 

4026 B.7.1.2.5 Local Modes 

4027 Noncanonical mode is provided to allow fast bursts of input to be read efficiently 

4028 while still allowing single-character input. 

4029 The ECHONL function historically has been in many implementations. Since 

4030 there seems to be no technical problem with supporting ECHONL, it is included in 

4031 POSIX.l to increase consensus. 

4032 The alternate behavior possible when ECHOK or ECHOE are specified with 

4033 ICANON is permitted as a compromise depending on what the actual terminal 

4034 hardware can do. Erasing characters and lines is preferred, but is not always 

4035 possible. 

4036 B.7.1.2.6 Special Control Characters 

4037 Permitting VMIN and VTIME to overlap with VEOF and VEOL was a compromise 

4038 for historical implementations. Only when backwards compatibility of object code | 

4039 is a serious concern to an implementor should an implementation continue this 

4040 practice. Correct applications that work with the overlap (at the source level) 

4041 should also work if it is not present, but not the reverse. 
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4042 B.7.1.2.7 Baud Rate Values 

4043 There is no additional rationale provided for this subclause. 

4044 B.7.1.3 Baud Rate Functions 

4046 The term baud is used historically here, but is not technically correct. This is 

4046 properly “bits per second,” which may not be the same as “baud.” However, the 

4047 term is used because of the historical usage and understanding. 

4048 These functions do not take numbers as arguments, but rather symbolic names. 

4049 There are two reasons for this: 

4050 — Historically, numbers were not used because of the way the rate was stored 

4061 in the data structure. This is retained even though an interface function is 

4052 now used. 

4053 — More importantly, only a limited set of possible rates is at all portable, and 

4054 this constrains the application to that set. 

4066 There is nothing to prevent an implementation to accept, as an extension, a 

4056 number (such as 126) if it wished, and because the encoding of the Bxxx symbols 

4057 is not specified, this can be done so no ambiguity is introduced. 

4068 Setting the input baud rate to zero was a mechanism to allow for split baud rates. 

4069 Clarifications to this version of POSIX. 1 have made it possible to determine if split 

4060 rates are supported and to support them without having to treat zero as a special 

4061 case. Since this functionality is also confusing, it has been declared obsolescent. 

4062 The 0 argument referred to is the literal constant 0, not the symbolic constant BO. 

4063 POSIX.l does not preclude BO from being defined as the value 0; in fact, imple- 

4064 mentations will likely benefit from the two being equivalent. POSIX. 1 does not 

4065 fully specify whether the previous cfsetispeedi ) value is retained after a tcgetattr( ) 
40?6 as the actual value or as zero. Therefore, portable applications should always set 

4067 both the input speed and output speed when setting either. 

4068 In historical implementations, the baud rate information is traditionally kept in 

4069 c_cflag. Applications should be written to presume that this might be the case 

4070 (and thus not blindly copy c_cflag ) but not to rely on it, in case it is in some other 

4071 field of the structure. Setting the c_cflag field absolutely after setting a baud rate 

4072 is a nonportable action because of this. In general, the unused parts of the flag 

4073 fields might be used by the implementation and should not be blindly copied from 

4074 the descriptions of one terminal device to another. 


4076 B.7.2 General Terminal Interface Control Functions 

4076 The restrictions described in this subclause on access from processes in back- 

4077 ground process groups controls apply only to a process that is accessing its con- 

4078 trolling terminal. (See B.7. 1.1.4). 

4079 Care must be taken when changing the terminal attributes. Applications should 

4080 always do a tcgetattr(), save the termios structure values returned, and then do a 

4081 tcsetattr() changing only the necessary fields. The application should use the 

4082 values saved from the tcgetattr() to reset the terminal state whenever it is done 
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with the terminal. This is necessary because terminal attributes apply to the 
underlying port and not to each individual open instance; that is, all processes 
that have used the terminal see the latest attribute changes. 

A program that uses these functions should be written to catch all signals and 
take other appropriate actions to assure that when the program terminates, 
whether planned or not, the terminal device’s state is restored to its original 
state. See also B.7.1. 

Existing practice dealing with error returns when only part of a request can be | 
honored is based on calls to the ioctl () function. In historical BSD and System V | 
implementations, the corresponding ioctl() returns zero if the requested actions | 
were semantically correct, even if some of the requested changes could not be | 
made. Many existing applications assume this behavior and would no longer | 
work correctly if the return value were changed from zero to -1 in this case. | 

Note that either specification has a problem. When zero is returned, it implies | 
everything succeeded even if some of the changes were not made. When -1 is | 
returned, it implies everything failed even though some of the changes were | 
made. | 

Applications that need all of the requested changes made to work properly should | 
follow tcsetattr() with a call to tcgetattrO and compare the appropriate field | 
values. 

B.7.2.1 Get and Set State 

The tcsetattr () function can be interrupted in the following situations: | 

— It is interrupted while waiting for output to drain. | 

— It is called from a process in a background process group ^nd SIGTTOU is | 

caught. | 

B. 7.2.2 Line Control Functions 

There is no additional rationale provided for this subclause. 

B.7.2.3 Get Foreground Process Group ID 

The tcgetpgrp () function has identical functionality to the 4.2BSD ioctl() function 
TIOCGPGRP except for the additional security restriction that the referenced ter- 
minal must be the controlling terminal for the calling process. 

In the case where there is no foreground process group, returning an error rather | 
than a positive value was considered. This was rejected because existing applica- | 
tions based on either IEEE Std 1003.1-1988 or 4.3BSD are likely to consider errors | 
from this call or the BSD equivalent to be catastrophic and respond inappropri- j 
ately. Such applications implicitly assume that this case does not exist, and the | 
positive return value is the only solution that permits them to behave properly j 
even when they do encounter it. No application has been identified that can | 
benefit from distinguishing between this case and the case of a valid foreground | 
process group other than its own. Therefore, requiring or permitting any other j 
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4123 solu M cause more application portability problems with no corresponding 

4124 benefit to applications. The value must be positive, not zero, because applications 

4125 may use the negation as the pid argument to kill(). In addition, the value 1 must 

4126 not be used so that an attempt to send a signal to this (nonexistent) process group 

4127 does not result in broadcasting a signal unintentionally. See also B.7.1. 1.2. 

4128 B.7.2.4 Set Foreground Process Group ID 

4129 The tcsetpgrp () function has identical functionality to the 4.2BSD ioctl() function 

4130 TIOCSPGRP except for the additional security restrictions that the referenced ter- 

4131 minal must be the controlling terminal for the calling process and the specified 

4132 new process group must be currently in use in the caller’s session. 


4133 B.8 Language-Specific Services for the C Programming Language 

4134 See the discussion of C functions in B. 1.1.1. | 

4136 Common usage may be defined by historical publications such as The C Program- | 

4136 ming Language { B46). 

4137 The null set of supported languages is allowed. 

4138 The list of functions comprises the list of “common-usage” functions and also 

4139 includes those that are not in common usage that are addressed by POSIX. 1. The 

4140 rules for common-usage conformance to POSIX.1 address whether the functions 

4141 that are not generally considered in common usage are implemented. There are a 

4142 large number of functions found in various systems that, although frequently 

4143 found, are not broadly enough available to be considered in common usage. The 

4144 signalQ function (although in common usage) is omitted because applications con- | 

4146 forming to POSIX.1 should use the more reliable sigactionO interface instead. | 

4146 B.8.1 Referenced C Language Routines 

4147 B.8.1. 1 Extensions to Time Functions 

4148 System V uses the TZ environment variable to set some information about time. 

4149 It has the form (spaces inserted for clarity): 

4150 std offset dst 

4151 where the first three characters (std) are the name of the standard time zone, the 

4152 digits that iollow ( offset ) represent the time added to the local time zone to arrive 

4153 at Coordinated Universal Time, and the next three characters (dst) are the name 

4154 of the summer time zone. The meaning of offset implies that most sites west of 
• 4155 the Prime Meridian will have a positive offset (preceded by an optional plus sign, 

4156 “+”), while most sites east of the Prime Meridian will have a negative offset (pre- 

4157 ceded by a minus sign, “-”). Both std and offset are required; if dst is missing, 

4158 summer time does not apply. 
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4169 Currently, the UNIX system localtimeO function translates a number of seconds 

4160 since the Epoch into a detailed breakdown of that time. This breakdown includes 

4161 (1) Time of day: Hours, minutes, and seconds. 

4162 (2) Day of the month, month of the year, and the year. 

4163 (3) Day of the week and day of the year (Julian day). 

4164 (4) Whether or not summer (daylight saving) time is in effect. 

4165 It is the first and last items that present a problem: the time of the day depends 

4166 on whether or not summer time is in effect. Whether or not summer time is in 

4167 effect depends on the locale and date. 

4168 Most historical systems had time-zone rules compiled into the C library. These 

4169 rules usually represented United States rules for 1970 to 1986. This did not 

4170 accommodate the changes of 1987, nor other world variations (Vi-hour time, dou- 

4171 ble daylight time, and solar time being common, but not complete, examples). 

4172 Some recent systems addressed these problems in various ways. 

4173 Having the rules compiled into the program made binary distributions that 

4174 accommodated all the variations (including sudden changes to the law), and per- 

4175 process rule changes, difficult at best. 

4176 POSIX.l includes a way of specifying the time zone in the TZ string, but only per- 

4177 mits one time-zone pattern at a time, thus not dealing with different patterns in 

4178 previous years and with such issues as solar time. Methods exist to deal with all 

4179 the problems above. The method in POSIX.1 appears to be simpler to implement 

4180 and may be faster in execution when it is adequate. POSIX.1 also permits an 

4181 implementation-defined rule set that begins with a colon. (The previous format 

4182 cannot begin with a colon.) 

4183 Rules of the form AAAn or AAAnBBB (the style used in many historical implemen- 

4184 tations) do not carry with them any statement about the start and end of daylight 

4185 time (neither the date nor the time of day; the default to 02:00 not applying if no 

4186 rule is present at all), thus implying that the implementation must provide the 

4187 appropriate rules. An implementation may provide those rules in any way it sees 

4188 fit, as long as the constraints implied by the TZ string as provided by the user are 

4189 met. Specifically, the implementation may use the string as an index into a table, 

4190 which may reside either on disk or in memory. Such tables could contain rules 

4191 that are sensitive to the year to which they are applied, again since the user did 

4192 not specify the exact rule. (Although impractical, every possible TZ string could 

4193 be represented in a table, as a detail of implementation; the less specific the user 

4194 is about the TZ string, the more freedom the implementation has to interpret it.) 

4195 There is at least one public-domain time-zone implementation (the Olson/Harris 

4196 method) that uses nonspecific TZ strings and a table, as described previously, and 

4197 handles all the general time-zone problems mentioned above. This implementa- 

4198 tion also appears in a late release of 4.3BSD. If this implementation honors all 

4199 the specifications provided in the TZ string, it would conform to POSIX.l. Nothing 

4200 precludes the implementation from adding information beyond that given by the 

4201 user in the TZ string. 

4202 The fully specified TZ environment variable extends the historical meaning to also 

4203 include a rule for when to use standard time and when to use summer time. 


284 


B Rationale and Notes 


Part 1: SYSTEM API [C LANGUAGE] 


ISO/TEC 9946-1: 1990 
IEEE Std 1003.1-1990 


4204 Southern hemisphere time zones are supported by allowing the first rule date 

4205 (change to summer time) to be later in the year than the second rule date (change 

4206 to standard time). 

4207 This mechanism accommodates the “floating day” rules (for example “last Sunday 

4208 in October”) used in the United States and Canada (and the European Economic 

4209 Community for the last several years). In theory, TZ only has to be set once and 
421^ then never touched again unless the law is changed. 

4211 Julian dates are proposed with two syntaxes, one zero-based, the other one-based. 

4212 They are here for historical reasons. The one-based counting («/) is used more 

4213 commonly in Europe (and on calendars people may use for reference). The zero- 

4214 based counting ( n ) is used currently in some implementations and should be kept 

4215 for historical reasons as well as being the only way to specify Leap Day. 

4216 It is expected that the leading colon format will allow systems to implement an 
'4217 even broader range of specifications for the time zone without having to resort to a 

4218 file or permit naming an explicit file containing the appropriate rules. 

4219 The specification in POSIX.l for TZ assumes that very few programs need to be 

4220 historically accurate as long as the relative timing of two events is preserved. 

4221 Summer time is governed by both locale and date. This proposal only handles the 

4222 locale dependency. Using an implementation-defined file format for either the 

4223 entire TZ variable or to specify the rules for a particular time zone is allowed as a 

4224 means by which both the locale and date dependency can be handled. 

4226 Since historical implementations do not examine TZ beyond the assumed end of 

4226 dst, it is possible literally to extend TZ and break very little existing software. 

4227 Since much historical software does not function outside the US time zones, minor 

4228 changes to TZ (such as extending offset to be hh imm — as long as the colon and 

4229 minutes, :mm, are optional) should have little effect. 

4230 POSIX.1 is intentionally silent about values of TZ that do not fit either of the 

4231 specified forms. It simply requires that TZ values that follow those forms be 

4232 interpreted as specified. 

4233 B.8.1.2 Extensions to setlocalei) Function 

4234 The C Standard (2) defines a collection of interfaces to support international iza- 

4235 tion. One of the most significant aspects of these interfaces is a facility to set and 

4236 query the international environment. The international environment is a reposi- 

4237 tory of information that affects the behavior of certain functionality, namely 

4238 (1) Character Handling 

4239 (2) String Handling (i.e., collating) 

4240 (3) Date/Time Formatting 

4241 (4) Numeric Editing 

4242 The setlocalei) function provides the application developer with the ability to set 

4243 all or portions, called categories , of the international environment. These 

4244 categories correspond to the areas of functionality, mentioned above. The syntax 

4245 for setlocalei ) is the following: 
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4246 char *setlocale (int category, const char * locale ) ; ! 

4247 where category is the name of one of five categories, namely 

LC_CTYPE 
LC_C 0 LLATE 
LC_TIME 
LC_MONETARY 
LC_NUMERIC 

4263 In addition, a special value, called LC_ALL, directs setlocaleO to set all categories. 

4264 The locale argument is a character string that points to a specific setting for the 
4256 international environment, or locale. There are three preset values for the locale 

4256 argument, namely 

4257 "C" Specifies the minimal environment for C translation. If setlocaleO 

4258 is not invoked, the “C” locale is the default. 

4259 "posix" Specifies a locale that is the same as "C" for the attributes defined | 

4260 by the C Standard {2} and POSIX. 1, but may contain extensions. | 

4261 The wording permits extensions by standards, specifically that of | 

4262 ISO/IEC 9945-2 (B36), which is expected to use the same symbol, | 

4263 and by future versions of POSIX. 1. i 

4264 " " Specifies an implementation-defined native environment. 

4265 NULL Used to direct setlocaleO to query the current international 

4266 environment and return the name of the locale. 

4267 This subclause describes the behavior of an implementation of setlocaleO and its | 

4268 use of environment variables in controlling this behavior on POSIX.l-based sys- | 

4269 terns. There are two primary uses of setlocaleO- 

4270 (1) Querying the international environment to find out what it is set to; 

4271 (2) Setting the international environment, or locale , to a specific value. 

4272 The following subclauses describe the behavior of setlocaleO in these two areas. | 

4273 Since it is difficult to describe the behavior in words, examples will be used to 

4274 illustrate the behavior of specific uses. 

4275 To query the international environment, setlocaleO is invoked with a specific 

4276 category and the NULL pointer as the locale. The NULL pointer is a special direc- 

4277 tive to setlocaleO that tells it to query rather than set the international environ- 

4278 ment. The following syntax is used to query the name of the international 

, 4279 environment: 

W \ \lc_all 

", \ LCjCTYPE 

LCjCOLLATE 

setlocalei- LCTJME 

LC ^NUMERIC 
LC_MONETAR 

4280 The setlocaleO function returns the string corresponding to the current intema- 

4281 tional environment. This value may be used by a subsequent call to setlocaleO to 



4248 

4249 
4260 

4251 

4252 
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reset the international environment to this value. However, it should be noted 
that the return value from setlocaleO is a pointer to a static area within the func- 
tion and is not guaranteed to remain unchanged [i.e., it may be modified by a sub- 
sequent call to setlocaleO ]. Therefore, if the purpose of calling setlocaleO is to 
save the value of the current international environment so it can be changed and 
reset later, the return value should be copied to an array of char in the calling 
program. 

There are three ways to set the international environment with setlocaleO : 

setlocale (category, string) 

This usage will set a specific category in the international 
environment to a specific value corresponding to the value of 
the string. A specific example is provided below: 

setlocale (LC_ALL, "Fr_FR. 8859 " ) ; 

In this example, all categories of the international environment 
will be set to the locale corresponding to the string 
"Fr_FR. 8859", or to the French language as spoken in France 
using the ISO 8859-1 code set. 

If the string does not correspond to a valid locale, setlocaleO 
will return a NULL pointer and the international environment 
is not changed. Otherwise, setlocaleO will return the name of 
the locale just set. 

setlocale {category, "C") 

The C Standard (2) states that one locale must exist on all con- 
forming implementations. The name of the locale is "C" and 
corresponds to a minimal international environment needed to 
support the C programming language. 

setlocale {category, "") 

This will set a specific category to an implementation-defined 
default. ForJPOSIX.l -based systems, this corresponds to the 
value of the environment variables. 


B.8.2 C Language Input/Output Functions 
B.8.2.1 Map a Stream Pointer to a File Descriptor 

Without some specification of which file descriptors are associated with these 
streams, it is impossible for an application to set up the streams for another appli- 
cation it starts with forkO and exec. In particular, it would not be possible to 
write a portable version of the sh command interpreter (although there may be 
other constraints that would prevent that portability). 


B.8.2.2 Open a Stream on a File Descriptor 

The file descriptor may have been obtained from openO, creatO, pipeO, dup 0, or 
fcntlO’t inherited through forkO or exec; or perhaps obtained by implementation- 
dependent means, such as the 4.3BSD socketO call. 
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4323 The meanings of the type arguments of fdopenO and fopen () differ. With fdo- 

4324 pen (), open for write ("w" or "w+") does not truncate, and append ("a" or "a+") 

4325 cannot create for writing. There is no need for "b" in the format due to the 

4326 equivalence of binary and text files in POSIX.l. See B. 1.1.1. Although not expli- 

4327 citly required by POSIX. 1, a good implementation of append ("a") mode would 

4328 cause the 0_APPEND flag to be set. 

4329 B. 8 . 2.3 Interactions of Other FILE- Type C Functions 

4330 Note that the existence of open streams on a file implies open file descriptors and 

4331 thus affects the timestamps of the file. The intent is that using stdio routines to 

4332 read a file must eventually update the access time, and using them to write a file 

4333 must eventually update the modify and change times. However, the exact timing 

4334 of marking the st_atime, st_ctime , and stjntime fields cannot be specified, as that 

4335 would imply a particular buffering strategy. 

4336 The purpose of the rules about handles is to allow the writing of a program that 

4337 uses stdio and does some shell-like things; in particular, creating an open file for 

4338 a child process to use, where both the parent and child wish to use stdio , with the 

4339 consequences of buffering. In most cases, this cannot happen in the C Standard 

4340 (2) (because there is no way to create a second handle), but the systemO function 

4341 can cause this to occur, at least in most historical implementations. 

4342 Presently, POSIX.l deals mostly with output streams; input is implementation 

4343 defined. It should be possible to make input on seekable devices work for seek- 

4344 able files without affecting buffering strategies significantly. However, the details 

4345 have not been worked out fully and will be addressed in a future revision of 

4346 POSIX.l. The requirements on applications are unlikely to change [basically, 

4347 serving notice to the implementation that the use of a particular handle is (tem- 

4348 porarily) completed] and are symmetric to those for output. 

4349 There are some implied rules about interprocess synchronization, but no mechan- 

4350 ism is given, intentionally. In the simplest case, if the parent meets the require- 

4351 ments on all its files and then performs a forkO and a wait() before further 

4362 activity on them [and a fflushO on input files after that], the desired synchroniza- 

4353 tion will be achieved. Synchronization could in theory be done with signals, but 

4354 the only likely case is the one just described. The terms handle and active handle 

4355 were required to make the text readable and are not intended for use outside this 

4356 discussion. 

4357 Note that since exitO implies _exitO, a file descriptor is also closed by exitO- 

4358 Because a handle is either freshly opened, or if not must have handed off control 

4359 of the open file description as specified, the new handle is always ready to be used 

4360 (except for seeks) with no initialization. [A freshly opened stream has not yet 

4361 done any reads, as required by the C Standard [2], at least implicitly by the rules 

4362 associated with setvbufO.] 
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4367 A naive program used as a utility can be reasonably expected to work properly 

4368 when the constraints are met by the calling program because it will not hand off 
<4369 file descriptors except with closes. 

4370 The exec functions are treated specially because the application should always 

4371 fflushO everything before performing one of the exec functions. If stdout is avail- 

4372 able on the same open file description after the exec, it is a different stream, at 

4373 least because any unfiushed data will be discarded during the exec (similarly for 

4374 stdin). Process termination is also special because a process terminating due to a 

4375 signal or _exitO will not have the buffers flushed. 

4376 The fork () function also must be specially treated because it clones a number of 

4377 file descriptors simultaneously. Thus, all of them should be prepared for handoff 

4378 before the forkO. In effect, fork () creates a pair of handles that are improperly 

4379 dealt with unless, before the forkO , the first part of a handoff occurred. Note that 

4380 fflush(N\JLL) in the C Standard {2} is an appropriate way to do this for output. A 

4381 subsequent exec call [that does not succeed in calling exitO in some way] will 

4382 reduce the number of handles back to the original value (allowing for files that 

4383 are not close-on-exec), and, thus, preparations for exec need not necessarily do the 

4384 flush. However, because exitO closes all streams, if the exec fails, the application 

4385 must be careful to terminate with _exitO- 

4386 POSIX.l does not specify asynchronous I/O, and when dealing with asynchronous 

4387 I/O the problem of coordinating access to streams will be more difficult. If asyn- 

4388 chronous I/O is provided as an extension, the problems it introduces in this area 

4389 should be addressed as part of that extension. 

4390 It may be that functions such as systemO and popen (), currently being considered 

4391 for ISO/IEC 9945-2 (B36), will have to perform some of these operations. 

4392 The introduction of underlying functions allows generic reference to errno values 

4393 returned by those functions and also to other side effects (as required in the han- 

4394 dies discussion above). It is not intended to specify implementation, although 

4395 many implementations may in fact use those functions. The C Standard (2) says 

4396 very little about errno in the context of stdio. In the more restricted POSIX. 1 

4397 environment, providing a reasonable set of errno values become possible. 

4398 

4399 B.8.2.3. 1 fopen O 

4400 There is no additional rationale provided for this subclause. 

4401 B.8.2.3.2 fcloseO 

4402 The fcloseO function is required to synchronize the buffer pointer with the file 

4403 pointer (unless it already is, which would be the case at EOF). Functionality 

4404 equivalent to 


4363 In requiring the seek to an appropriate location for the new handle, the applica- 

4364 tion is required to know what it is doing if it is passing streams with seeks 

4365 involved. If the required seek is not done, the results are undefined (and in fact 

4366 the program probably will not work on many common implementations). 
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4405 f seek (stream, f tell (stream) , seek_set) 

4406 does this nicely. The exception for devices incapable of seeking is an obvious 

4407 requirement, but the implication is that there is no way to reliably read a buffered 

4408 pipe and hand off handles. This is the situation in historical implementations 

4409 and is inherent in any "read-ahead” buffering scheme. This limitation is also 

4410 reflected in the handle hand-off rules. 
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4411 Note that the last byte read from a stream and the last byte read from an open 

4412 file description are not necessarily the same; in most cases the open file 
1413 description’s pointer will be past that of the stream because of the stream’s read- 
4414 ahead. 

44 16 B.8.2.3.3 freopen ( ) 

4416 There is no additional rationale provided for this subclause. 

4417 B.8.2.3.4 (flush ( ) 

4418 There is no additional rationale provided for this subclause. I 

44 19 B.8.2.3.5 fgetc ( ), fgets ( ), fre.ad ( ), getc ( ), getchari ), gets ( ), scanfi ) , f scanfi ) 

4420 There is no additional rationale provided for this subclause. 

4421 B.8.2.3.6 fputcO , fputsi), fwritei), putc(), putchari), puts (), print fi), 

4422 vprintfi), vfprintfi) 

4423 There is no additional rationale provided for this subclause. 

4424 B.8.2.3.7 fseeki), rewindi) 

4426 The fseeki,) function must operate as specified to make the case where seeking is 

4426 being done work. The key requirement is to avoid an optimization such that an 

4427 fseeki) would not result in an Iseek () if the fseeki) pointed within the current 

4428 buffer. This optimization is valuable in general, so it is only required after an 

4429 fflushi). 

4430 B.8. 2.3.8 perrori) 

4431 There is no additional rationale provided for this subclause. 

4432 B.8.2.3.9 tmpfilei) 

4433 There is no additional rationale provided for this subclause. 

44 :i 4 B.8.2.3.10 ftelli) 

4435 In append mode, a fflushi) will change the seek pointer because of possible writes | 

4436 by other processes on the same file. An fseeki) reflects the underlying file’s file | 

4437 offset, which is not necessarily the end of the file. Implementors should be aware | 

4438 that the operating system itself (not some in-memory approximation) of the file | 

4439 offset should be queried when in append mode. I 

4440 B.8.2.3.11 Error Reporting 

4441 POSIX. 1 intentionally does not require that all errors detected by the underlying | 

4442 functions be detected by the functions listed here. There are many reasonable | 

4443 cases where this might not occur; for example, many of the functions with writci) | 

4444 as an underlying function might not detect a number of error conditions in cases | 

4445 where they simply buffer output for a subsequent flush. I 
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[ENOMEM] was considered for addition as an explicit possible error because most 
implementations use malloci). This was not done because the scope does not 
include “out of resource” errors. Nevertheless this is the most likely error to be 
added to the possible error conditions. Other implementation-defined errors, par- 
ticularly in the f*openi) family, are to be expected, and the generic rules about 
adding (or deleting) possible errors apply, except that it is expected that 
implementation-defined changes in the error set returned by openi) would also 
apply to fopen () [unless the condition cannot possibly happen in fopen (), which 
may be possible, but appears unlikely]. 


B.8.2.3.12 exit (), abort () 


POSIX.1 intends that processing related to the aborti) function will occur unless 
“the signal SIGABRT is being caught, and the signal handler does not return,” as 
defined by the C Standard {2}. This processing includes at least the effect of 
fc lose i) on all open streams, and the default actions defined for SIGABRT. 


The aborti) function will override blocking or ignoring the SIGABRT signal. 
Catching the signal is intended to provide the application writer with a portable 
means to abort processing, free from possible interference from any 
implementation-provided library functions. 


Note that the term “program termination” in the C Standard (2) is equivalent to 
“process termination” in POSIX.1. 


4466 B.8.2.4 Operations on Files — the remove i ) Function 


4467 There is no additional rationale provided for this subclause. 


B.8.3 Other C Language Functions 


B.8.3.1 Nonlocal Jumps 


4470 The C Standard {2} specifies various restrictions on the usage of the setjmpi) 
»47i macro in order to permit implementors to recognize the name in the compiler and 


4472 not implement an actual function. These same restrictions apply to the sig- 

4473 setjmpi) macro. 


4476 The distinction between setjmp ( Vlongjmp ( ) and sigsetjmpi)/siglongjmpi) is only 

4477 significant for programs that use the sigactioni), sigprocmaski), or sigsuspendi) 


,4478 functions. Since earlier implementations did not have signal masks, only a single 
4479 pair was provided. 


4.2BSD and 4.3BSD systems provide functions named jsetjmpi) and _longjmpi) 
that, together with setjmpi) and longjmpi), provide the same functionality as sig- 
setjmpi) and siglongjmpi). On those systems, setjmpi) and longjmpi) save and 
restore signal masks, while _setjmpi) and Jongjmpi) do not. On System V 
Release 3 and in corresponding issues of the SVID (B39), setjmpi) and longjmpi) 
are explicitly defined not to save and restore signal masks. In order to permit 
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«74 There are processors that cannot easily support these calls, but this was not con- | 
4475 sidered a sufficient reason to exclude them. 
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4486 existing practice in both cases, the relation of setjmpO and longjmpO to signal 

4487 masks is not specified, and a new set of functions is defined instead. 

4488 B.8.3.2 Set Time Zone 

4489 There is no additional rationale provided for this subclause. 

4490 B.8.3.3 Omitted Memory Management 

4491 The brk () and sbrkO functions frequently were proposed for inclusion in POSIX. 1 , 

4492 but they were excluded deliberately. See also B. 1 . 1 . The rationale for including 

4493 them is usually addressed to the argument that it is the sbrk( ) primitive that 

4494 makes it possible to implement some more general heap management system, 

4495 such as that provided for C by malloci) . The need for such functionality is fully 

4496 understood, but specifying it as a part of a standard would have the effect of limit- 

4497 ing the number of architectures that could support POSIX. 1 . It might also con- 

4498 strain languages whose memory-management model was not served by the sbrk ( ) 

4499 model. 

4500 Memory management is not excluded from POSIX. 1 : POSIX .1 relies on the 

4501 language to provide it, and in the C binding (as reflected in Section 8 ) it is pro- 

4502 vided by mallocO. It would be provided by new( ) in Pascal. In a language like 

4503 FORTRAN, which does not supply memory management to the user, it would be 

4504 undesirable to force the language binding to attempt to include such a function. 

4505 It is reasonable to imagine a language that required a more powerful primitive 

4506 than sbrk () to be implemented, and standardizing sbrkO would only constrain 

4507 such future languages. 

4508 POSIX .1 is silent about mixed languages. Mixing languages that provide incompa- 

4509 tible memory-management mechanisms can yield unpredictable results. Future 

4510 standards that address mixing of languages should consider this issue. 

4511 Architectures that could not support sbrk () are also a limiting factor. In particu- 

4512 lar, architectures that do not present a model of a single linear address space 

4513 would be severely constrained by sbrkO, but are not so constrained by malloci) or 

4514 newO- 

4515 Each language should specify the memory-management primitives best suited to 

4516 that language. Whether the implementor chooses to use a more primitive 

4517 mechanism to implement that, or the implementor chooses to directly implement 

4518 the language function in the kernel, is not a proper concern of the developers of 

4519 POSIX. 1 , nor should it be for any portable application. An application that 

4520 presumes the sbrkO model of memory management will not port to all architec- 

4521 tures in any case, for the same reasons that sbrkO itself does not work on those 

4522 architectures. No true gain in application portability would be achieved by man- 

4523 dating such an interface. This implies that an implementor of software that 

4524 wishes to port to multiple platforms and that attempts to implement its own 

4525 memory management rather than relying on language-supplied functions must be 

4526 prepared to deal with multiple platform-supplied primitives and, because it is 

4527 doing its own memory management inherently, cannot be considered, or be made 

4528 to be, portable in that regard. 
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4529 B.9 System Databases 

4530 At one time, this section was entitled Passwords, but this title was changed as all 

4531 references to a “password file” were changed to refer to a “user database.” 

4532 B.9.1 System Databases 

4533 There are no references in POSIX .1 to a passwd file or a group file , and there is no 

4534 requirement that the group or passwd databases be kept in files containing edit- 
4536 able text. Many large timesharing systems use passwd databases that are 

4536 hashed for speed. Certain security Classifications prohibit certain information in 

4537 the passwd database from being publicly readable. 



£ 


4538 The term “encoded” is used instead of “encrypted” in order to avoid the implemen- 

4539 tation connotations (such as reversibility or use of a particular algorithm) of the 

4540 latter term. 
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The getgrentO, setgrentO , endgrentO, getpwentO> setpwentO, and endpwentO 
functions are not included in POSIX .1 because they provide a linear database 
search capability that is not generally useful [the getpwuidO , getpwnam 0 , get- 
grgidO, and getgrnamO functions are provided for keyed lookup] and because in 
certain distributed systems, especially those with different authentication 
domains, it may not be possible or desirable to provide an application with the 
ability to browse the system databases indiscriminately. 

A change from historical implementations is that the structures used by these 
functions have fields of the types gid_t and uidj , which are required to be defined 
in the header <sys/types . h>. POSIX .1 has not changed the synopses of these 
functions to require the inclusion of this header, since that would invalidate a 
large number of existing applications. Implementations must ensure that these 
types are defined by the inclusion of <grp . h> and <pwd . h>, respectively, without 
imposing any namespace pollution or errors from redefinition of types. 

POSIX .1 is silent about the content of the strings containing user or group names. 
These could be digit strings. POSIX .1 is also silent as to whether such digit 
strings bear any relationship to the corresponding (numeric) user or group ID. 

B.9.2 Database Access 
B.9.2.1 Group Database Access 

There is no additional rationale provided for this subclause. 

B.9.2.2 User Database Access 

There is no additional rationale provided for this subclause. 
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4663 B.10 Data Interchange Format 

4664 B.10.1 Archive/Interchange File Format 

4566 There are three areas of interest associated with file interchange: 

45641 (1) Media. There are other existing standards that define the media used for 

4fi<57 data interchange. 

456 « (2) User Interface. This rightfully should be in the shell and utilities stan- | 

4569 dard, under development as ISO/IEC 9945-2 (B36). I 

4570 (3) Format of the Data. None of the groups currently developing POSIX stan- | 

4571 dards address topics that match this area. The groups felt that this area | 

4572 is closest to the types of things that should be in the POSIX.1 document, | 

4573 as the level of that document most closely matches the level of data | 

4574 required. 

4576 There are two programs in wide use today: tar and cpio. There are many sup- 
4576 porters for each program. Four options were considered for POSIX.1: 

4677 (1) Make both formats optional. This was considered unacceptable because 

4578 it does not allow any portable method for data interchange. 

4579 (2) Require one format. 

4580 ( 3) Require one format with the other optional. 

4581 (4) Require both formats. 

4682 Both the Extended cpio and the Extended tar Formats are required by POSIX.1. 

4583 There are a number of concerns about defining extensions that are known to be 
4684 required by historical implementations. Failure to specify a consistent method to | 

4585 implement these extensions will limit portability of the data and, more impor- 

4586 tantly, will create confusion if these extensions are later standardized. 

4587 Two of these extensions that should be documented are symbolic links, which | 

4588 were defined by 4.2BSD and 4.3BSD systems, and high-performance (or contigu- 

4589 ous) files, which exist in a number of implementations and are now being con- 

4590 sidered for future amendments to POSIX.1. I 

4591 By defining these extensions, implementors are able to recognize these features 
4692 and take appropriate implementation-defined actions for these files. For example, 

4593 a high-performance file could be converted to a regular file if the system did not 

4594 support high-performance files; symbolic links might be replaced by normal hard 

4595 links. 

4596 The policy of not defining user interfaces to utilities preempted any description of | 
4697 a tar or cpio command. The behavior of the former command was described in 

4598 some detail in previous drafts. 

4599 The possibilities for transportable media include, but are not limited to 

4600 (1) 12,7 mm (0,5 in) magnetic tape, 9 track, 63 bpmm (1 600 bpi) I 

4601 (2) 12,7 mm (0,5 in) magnetic tape, 9 track, 246 cpmm (6 250 cpi) I 




; 

! 


: 

i 


294 


B Rationale and Notes 


Part 1: SYSTEM API [C LANGUAGE] 


ISO/EEC 9945-1: 1990 
IEEE Std 1003.1-1990 


4602 (3) QIC-11, 6,30 mm (0,25 in) streamer tape I 

4603 (4) QIC-24, 6,30 mm (0,25 in) streamer tape I 

4604 (5) 130 mm (5,25 in) diskettes, 9 512-byte sectors/track, 3,8 tpmm (96 tpi) | 

4606 (6) 130 mm (5,25 in) diskettes, 9 512-byte sectors/track, 1,9 tpmm (48 tpi) | 

4606 When selecting media, issues such as character frame size also need to be | 

4607 addressed. The easiest environment for interchange occurs when 8-bit frames are | 

4608 used. I 

4609 The utilities are not restricted to work only with transportable media: existing | 

4610 related utilities are often used to transport data from one place to another in the 

4611 file hierarchy. 

4612 The formats are included to provide implementation-independent ways to move 

4613 files from one system to another and also to provide ways for a user to save data 

4614 on a transportable medium to be restored at a later date. Unfortunately, these 

4615 two goals can contradict each other, as system security problems are easy to find 

4616 in tape systems if they are not protected. Thus, there are strict requirements 

4617 about how the mechanism to copy files shall react when operated by both 

4618 privileged and nonprivileged users. The general concept is that a privileged (his- 

4619 torically using the ISUID bit in the file’s mode with the owner UID of the file set to 

4620 super-user) version of the utility (or one operated by a privileged user) can be 

4621 used as a save/restore scheme, but a nonprivileged version is used to interpret 

4622 media from a different system without compromising system security. 

4623 Regardless of the archive format used, guidelines should be observed when writ- 

4624 ing tapes to be read on other systems. Assuming the target system conforms to 

4625 POSIX.1, archives created should only use definitions found in POSIX.1 (e.g., file 

4626 types, minimum values as found in Section 2) and should only use relative path- | 

4627 names (i.e., no leading slash). I 

4628 Both tar and cpio formats have traditionally been used for both exchange of 
.4629 information and archiving. These formats have a number of features that facili- 

4630 tate archiving, for example, the'ability to store information about a file that is a 

4631 device. POSIX.1 does not assume this kind of data is portable. It is intended that 

4632 these formats provide for the portable exchange of source information between 

4633 dissimilar systems. This requires specification of the character set to be used | 

4634 (ISO/IEC 646 {1}) when these formats are used to write source information. The | 

4635 1 99 0 version of ISO/IEC 646 {1} IRV was selected as the international character set | 
4<>36 that corresponds most directly to the ASCII set used in many historical implemen- | 

4637 tations. The 1990 version was chosen over the 1983 version because it defines | 

4638 ' $ ' as the currency symbol in the IRV, as opposed to the starburst-like generic | 

4639 currency symbol. Note that ISO/IEC 646 {1} is a safe lowest-common-denominator | 

4640 character set and that interchange of larger character sets is permitted by mutual | 

4641 agreement. Using any other character set (such as ISO 8859-1 {B34} or some mul- | 

4642 tibyte character set) reduces the number of machines to which interchange is | 

4643 guaranteed. I 

4644 All data written by format-creating utilities and read by form at- reading utilities 

4645 is an ordered stream of bytes. The first byte of the stream should be first on the 

4646 medium, the second byte second, etc. On systems where the hardware swaps 

4647 bytes or otherwise rearranges the byte stream on output or input, the 
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implementor of these utilities must compensate for this so that the data on the 
storage device retains its ordered nature. 

POSIX.l describes two different formats for data archiving and interchange. | 
Strong support for both formats was evident through the balloting process. This j 
is a clear indication of the need for both formats due to existing practice. The bal- 
loting process also defined a number of deficiencies of each format. The strong 
support indicates that these deficiencies are not sufficient to remove either format 
from POSIX.l, but will need to be addressed in future amendments to POSIX.l. It 
was not practical to remedy these deficiencies during the balloting process. Con- 
siderable thought and review must occur before making any changes to these for- 
mats. It was felt that the best solution is to advise implementors and application 
writers of these deficiencies by documenting them in the rationale and to include 
both formats in POSIX.1. 

The developers of POSIX.1 recognize the desirability for migration toward one | 
common format and have been made aware of some strong inputs to consider both | 
formats in light of existing practice, current technology trends, and the POSIX | 
standards activities such as security and high-performance systems, and to | 
develop one format that is technically superior. This format will be incorporated | 
into a future amendment to POSIX.l when it is developed. i 

The deficiencies that have been identified in the existing formats are as follows. 
The size of a file link is limited to 100 characters in tar. A number of fields in 
the cpio header ( cjilesize , cjiev, cj.no, cjnode , and cjrdev ) are too short to 
support values that POSIX.l allows these fields to contain. Some existing imple- 
mentations and current trends in development will require the ability to 
represent even larger values in these fields. The cpio format does not provide a 
mechanism to represent the user and group IDs symbolically, and a range of 
implementation-defined file types have not been reserved for the user. The cpio 
format specification does not reserve any formats for implementation-defined 
usage. The extensions that have been made to cpio for POSIX.1 are compatible 
with existing versions of cpio. Correction of some of these deficiencies would 
make existing versions of cpio behave unpredictably. When these changes are 
made the cpio magic number will have to be changed. 

This clause uses the term file name’, note that filename and file name are not | 
synonyms; the latter is a synonym for pathname, in that it includes the slashes 
between filenames. 

In earlier drafts, the word “local” was used in the context of “file system” and was 
taken (incorrectly) to be related to “remotely mounted file system.” This was not 
intended. The term “(local) file system” refers to the file hierarchy as seen by the 
utilities, and “local” was removed because of this confusion. 

B.10.1.1 Extended tar Format 

The original model for this facility is the 4.3BSD or Version 7 tar program and 
format, but the format given here is an extension of the traditional tar format. 
The name USTAR was adopted to reflect this. 

This description reflects numerous enhancements over previous versions. The 
goal of these changes was not only to provide the functional enhancements 
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4693 desired, but also to retain compatibility between new and old versions. This corn- 

4694 patibility has been retained. Archives written using the old archive format are 

4695 compatible with the new format. Archives written using this new format may be 

4696 read by applications designed to use the old format as long as the functional 

4697 enhancements provided here are not used. This means the user is limited to 

4698 archiving only regular type files and nonsymbolic links to such files. 

4699 Implementors should be aware that the previous file format did not include a 

4700 mechanism to archive directory type files. For this reason, the convention of 

4701 using a file name ending with slash was adopted to specify a directory on the 

4702 archive. 

4703 The total size of the name and prefix fields have been set to meet the minimum 

4704 requirements for {PATH_MAX}. If a pathname will fit within the name field, it is 
4706 recommended that the pathname be stored there without the use of the prefix 

4706 field. Although the name field is known to be too small to contain (PATH_MAX) 

4707 characters, the value was not changed in this version of the archive file format to 

4708 retain backward compatibility, and instead the prefix was introduced. Also, 

4709 because of the earlier version of the format, there is no way to remove the restric- 

4710 tion on the linkname field being limited in size to just that of the name field. 

4711 The size field is required to be meaningful in all implementation extensions, 

4712 although it could be zero. This is required so that the data blocks can always be 

4713 properly counted. 

4714 It is suggested that if device special files need to be represented that cannot be 

4715 represented in the standard format that one of the extension types ('a'-'z') be 

4716 used, and that the additional information for the special file be represented as 

4717 data and be reflected in the size field. 

4718 Attempting to restore a special file type, where it is converted to ordinary data 

4719 and conflicts with an existing file name, need not be specially detected by the util- 

4720 ity. If run as an ordinary user, a format-reading utility should not be able to 

4721 overwrite the entries in, for example, /dev in any case (whether the file is con- 

4722 verted to another type or not). If run as a privileged user, it should be able to do 

4723 so, and it would be considered a bug if it did not. The same is true of ordinary 

4724 data files and similarly named special files; it is impossible to anticipate the 

4725 user’s needs (who could really intend to overwrite the file), so the behavior should 

4726 be predictable (and thus regular) and rely on the protection system as required. 

4727 The values 2 and / 7 / in the typeflag field are intended to define how symbolic 

4728 links and contiguous files can be stored in a tar archive. POSIX.1 does not 

4729 require the symbolic link or contiguous file extensions, but does define a standard 

4730 way of archiving these files so that all conforming systems can interpret these file 

4731 types in a meaningful and consistent manner. On a system that does not support 

4732 extended file types, the format-interpreting utility should do the best it can with 

4733 the file and go on to the next. 

4734 B. 10 . 1.2 Extended cpio Format 

4735 The model for this format is the existing System V cpio — c data interchange for- 

4736 mat. This model documents the portable version of cpio format and not the 

4737 binary version. It has the flexibility to transfer data of any type described within 
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the POSIX. 1 standard, yet is extensible to transfer data types specific to exten- 
sions beyond POSIX.l (e.g., symbolic links or contiguous files). Because it 
describes existing practice, there is no question of maintaining upward 
compatibility. 

This subclause does not standardize behavior for the utility when the file type is | 
not understood or supported. It is useful for the utility to report to the user what- 
ever action is taken in this case, though POSIX. 1 neither requires nor recommends 
this. 

B. 10. 1.2.1 cpio Header 

There has been some concern that the size of the c_ino field of the header is too 
small to handle those systems that have very large i-node numbers. However, the 
cjno field in the header is used strictly as a hard link resolution mechanism for 
archives. It is not necessarily the same value as the i-node number of the file in 
the location from which that file is extracted. 

B.10.1.2.2 cpio File Name 

For most historical implementations of the cpio utility, (PATH_MAX) bytes can be 
used to describe the pathname without the addition of any other header fields (the 
null byte would be included in this count). {PATH.MAX} is the minimum value for 
pathname size, documented as 256 bytes in Section 2. However, an implementa- | 
tion may use c_namesize to determine the exact length of the pathname. With the 
current description of the cpio header, this pathname size can be as large as a 
number that is described in six octal digits. 

B. 10.1.2.3 cpio File Data 

There is no additional rationale provided for this subclause. 

B.10.1.2.4 cpio Special Entries 

These are provided to maintain backward compatibility. 

B.10.1.2.5 cpio Values 

Three values are documented under the c_mode field values to provide for extensi- 
bility for known file types: 

0110000 Reserved for contiguous files. The implementation may treat 
the rest of the information for this archive like a regular file. If 
this file type is undefined, the implementation may create the 
file as a regular file. 

0120000 Reserved for files with symbolic links. The implementation 
may store the link name within the data portion of the file. If 
this type is undefined, the implementation may not know how 
to link this file or be able to understand the data section. The 
implementation may decide to ignore this file type and output a 
warning message. 
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0140000 Reserved for sockets. If this type is undefined on the target 
system, the implementation may decide to ignore this file type 
and output a warning message. 

This provides for extensibility of the cpio format while allowing for the ability to 
read old archives. Files of an unknown type may be read as “regular files” on 
some implementations. On a system that does not support extended file types, 
the format-interpreting utility should do the best it can with the file and go on to 
the next. 

B.10.1.3 Multiple Volumes 

Multivolume archives have been introduced in a manner that has become a de 
facto standard in many implementations. Though it is not required by POSIX. 1, 
classical implementations of the form at- reading and -creating utility, upon read- 
ing logical end-of-file, check to see if an error channel is open to a controlling ter- 
minal. The utility then produces a message requesting a new medium to be made 
available. The utility waits for a new medium to be made available by attempting 
to read a message to restart from the controlling terminal. In all cases, the com- 
munication with the controlling terminal is in an implementation-defined 
manner. 

This subclause (10.1.3) is intended to handle the issue of multiple volume 
archives. Since the end-of-medium and transition between media are not properly 
part of POSIX.l, the transition is described in terms of files; the word “file” is used 
in a very broad, but correct, sense — a tape drive is a file. The intent is that files 
will be read serially until the end-of-archive indication is encountered and that 
file or media change will be handled by the utilities in an implementation-defined 
manner. 

Note that there was an issue with the representation of this on magnetic tape, 
and POSIX.l is intended to be interpreted such that each byte of the format is 
represented on the media exactly once. In some current implementations, it is 
not deterministic whether encountering the end-of-medium reflector foil on mag- 
netic tape during a write will yield an error during a subsequent readO of that 
record, or if that record is actually recorded on the tape. It is also possible that 
read() will encounter the end-of-medium when end-of-medium was not encoun- 
tered when the data was written. This has to do with conditions where the end of 
[magnetic) record is in such a position that the reflector foil is on the verge of 
being detected by the sensor and is detected during one operation and not on a 
later one, or vice versa. 

An implementation of the format-creating utility must assure when it writes a 
record that the data appears on the tape exactly once. This implies that the pro- 
gram and the tape driver work in concert. An implementation of the format- 
reading utility must assure that an error in a boundary condition described above 
will not cause loss of data. 

The general consensus was that the following would be considered as correct 
operation of a tape driver when end-of-medium is detected: 

(1) During writing, either 
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(a) The record where the reflector spot was detected is backspaced ovei 
by the driver so that the trailing tape mark that will be written on 
close () will overwrite. Writing the tape mark should not yield an 
end-of-medium condition, or 

(b) The condition is reported as an error on the writeO following the 
one where the end-of-medium is detected (the one where the end- 
of-medium is actually detected completing successfully). No data 
will be actually transferred on the write 0 reporting the error, the 
subsequent close 0 would write a tape mark following the last 
record actually written. Writing the tape mark, and writing any 
subsequent records, should not yield any end-of-medium conditions. 

[The latter behavior permits the implementation of ANSI standard labels 
because several records (the trailer records) can be wntten after the end- 
of-medium indications. It also permits dealing with, for example, COBOL 
“ON” statements.) 

(2) During reading, the end-of-medium indicator is simply ignored, presum- 
ing that a tape mark (end-of-file) will be recorded on the magnetic 
medium and that the reflector foil was advisory only to the wntei). 

Systems where these conditions are not met by the tape driver should assure that 
the format-creating and -reading utilities assure proper representation and 
interpretations of the flies on the media in a way consistent with the above recom- 
mendations. 

The typical failures on systems that do not meet the above conditions are either 

(1) To leave the record written when the end-of-medium is encountered on 
the tape but to report that it was not written. The format-creating util- 
ity would then rewrite it, and then the format-reading utility could see 
the record twice if the end-of-medium is not sensed during the read 
operations, or 

(2) The write 0 occurs uneventfully, but the readO senses the error and does 
not actually see the data, causing a record to be omitted. 

Nothing in POS1X.1 requires that end-of-medium be determined by anything on 
the medium itself (for example, a predetermined maximum size would be an 
acceptable solution for the format-creating utility). The format-reading utility 
must be able to readi) tapes written by machines that do use the whole medium, 
i however. 

i On media where end-of-medium and end-of-file are reliably coincident, such as 
r disks, end-of-medium and end-of-file can be treated as synonyms. 

i Note that partial physical records [corresponding to a single wnteO ] can bewnt- 
i ten on some media, but that only full physical records will actually be wntten to 
a magnetic tape, given the manner in which the tape operates. 
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Annex C 

(informative) 

Header Contents Samples 


1 The material in this informative annex serves as an index to which symbols 

2 should appear in which headers in a system that conforms to POS1X.1 with C 

3 Standard Language-Dependent System support. 

4 This is only an index, and any conflicts with the actual body of any relevant stun- 

5 dard shall be resolved in favor of that standard. The actual body of the declara- 

o tion was omitted in part because this is an index and in part to avoid any possible 

7 conflict with the standards. 

s Where it is known that a symbol or header is not required for Common Usage C 

9 Language-Dependent System support, the name is followed by an asterisk (*). 

10 Omission of an asterisk does not imply that the symbol is required for Common- 

u Usage C. For Common-Usage C, although the location of symbols is typical, it is 

12 not to be taken as a requirement: POSIX.1 is quite explicit that there is no 

is requirement except that differences from the C Standard (2) be documented. 

14 Generally, where it is stated that functions are defined in a header, macros are 

is permitted as acceptable alternatives by both standards. See the bodies of the 

16 standards for details. 

17 <assert.h> • 

is The header defines the macro ^ 

19 assertO 

20 and makes reference to the macro 


22 <ctype.h> 

23 The header declares the functions 

24 isalnum () isdigitO islowert) ispuncH ) isupperO tolowerO 

25 isalphaO isgraphO isprintO isspace () isxdigitO toupperi) 

26 iscntrlO 
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27 

<dirent -h> 



1 



69 

28 

The header defines the typedef 

• 


1 



60 

29 

DIR 



1 



61 

30 

and declares the structure 



1 



62 

31 

dirent 



1 



63 








64 

32 

with structure element member 



1 



65 








66 

33 

djiame 



1 


* 

67 

34 

and declares functions 



1 



68 

35 

closedirO opendirO readdirO rewinddirO 


1 











69 

36 

<errno .h> 



1 



70 








71 

37 

The header defines the macros 



1 



72 

38 

E2BIG E&ST EMLINK 

ENOMEM 

EPERM 

1 



73 

74 

39 

EACCES EFAULT ENAMETOOLONG ENOSPC 

EPIPE 

1 



75 

40 

EAGAIN EFBIG ENFILE 

ENOSYS 

ERANGE 

1 



76 

41 

EBADF E1NTR ENODEV 

ENOTDIR 

EROFS 

1 



77 

42 

EBUSY EINVAL ENOENT 

ENOTEMPTY 

ESPIPE 

1 


78 

43 

ECHILD EIO ENOEXEC 

ENOTTY 

ESRCH 

1 



44 

EDEADLK EISDIR ENOLCK 

ENXIO 

EXDEV 

1 



79 

45 

EDOM EMFILE 



1 










80 

46 

and declares the external variable 



1 



81 

47 

errno 



1 



82 

48 

<fcntl .h> 



1 



83 

49 

The header defines the macros 



1 



84 

50 

FD_CLOEXEC FJ3ETFD 

0_ACCM0DE 0_N0NBL0CK 

1 




51 

F_DUPFD F_SETFL 

0_APPEND 0_RDONLY 

1 



85 

52 

F_GETFD F_SETLK 

0_CREAT 0_RDWR 

1 



63 

F_GETFL F.SETLKW 

0_EXCL 0_TRUNC 

1 




54 

F_GETLK F_UNLCK 

0_N0CITY 0_WRONLY 

1 




65 

F_RDLCK F_WRLCK 



1 




56 

and declares the structure 



1 




67 

flock 



1 




58 

with structure elements 



1 





l_len l_pid l_start Ijype Lwhence 

and the functions 

creatO fcntl() openO 
and may contain the macros 


SEEK.CUR 

SEEK_END 

SEEKJ3ET 

S_IRGRP 


SJROTH 

SJRUSR 

SJRWXG 

S_IRWXO 


SJRWXU 

SJSBLK 

SJSCHR 

SJSDIR 


S_ISFIFO 

SJSGID 

SJSREG 

SJSUID 


SJWGRP 

SJWOTH 

S_IWUSR 


S 

S 

S 


<float ,h>* 

The header defines the macros 


DBL_DIG* 

DBL.EPSILON* 

DBL_MANT_DIG* 

DBL_MAX* 

DBL_MAX_10_EXP* 

DBL_MAX_EXP* 

DBL_MIN* 

DBL_MIN_10_EXP* 

DBL_MIN_EXP* 

FLT_DIG* 


FLT_EPSILON« 

F LT_M ANT_D I G* 

FLT_MAX* 

FLT_MAX_10_EXP* 

FLT_MAX_EXP* 

FLT_MIN* 

FLT_MIN_10_EXP* 

FLT__MIN_EXP* 

FLT_RADIX« 

FLT_ROUNDS* 


LDBL_DIG* 

LDBL_EPSILON» 

LDBL_MANT_DIG* 

LDBL_MAX* 

LDBL_MAJOO_EXP* 

LDBL_MAX_EXP* 

LDBL_MIN» 

LDBL_MIN_10_EXP* 

LDBL_MIN_EXP* 


<grp.h> 

The header declares the structure 


group 

with structure elements 


gr_gid 

and the functions 
getgrgidi) 


grjnem grjiame 


getgrnam ( ) 
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.IXOTH 

.IXUSR 
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86 

climits .h> 


87 

The header defines the macros 

88 

ARG_MAX* 

NGROUPS_MAX 

89 

CHAR_B1T 

OPEN_MAX» 

90 

CHAR_MAX 

PATH_MAX» 

91 

CHAR_MIN 

PIPE_BUF* 

92 

CHILD_MAX* 

SCHAR_MAX 

93 

INT_MAX 

SCHAR_MIN 

94 

INT_MIN 

SHRT_MAX 

95 

LJNKJ4AX* 

SHRT_MIN 

96 

LONG_MAX 

SSIZE_MAX 

97 

L0NG_M1N 

STREAM_MAXD 

98 

MAX_CANON. 

TZNAME_MAX 

99 

MAX_INPUT. 

UCHAR_MAX 

100 

MB_LEN_MAX 

UINT_MAX 

101 

NAME_MAX. 

ULONG_MAX 
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USHRT_MAX 

_POSIX_ARG_MAX 

_POSIX_CHILD_MAX 

_POSIXJ,INK_MAX 

_POSIX_MAX_CANON 

_POSIX_MAX_INPUT 

_POSIX_NAME_MAX 

_P0S1X_NGR0UPS_MAX 

_POSIX_OPEN_MAX 

_POSIX_PATH_MAX 

_POSIX^PIPE_BUF 

_POSIX_SSIZE_MAX 

_POSIX_STREAM_MAX 

_POSIX_TZNAME_MAX 


102 The macros marked with □ shall be omitted from <limits . h> on specific imple- | 

103 mentations where the corresponding value is greater than or equal to the stated | 

104 minimum, but iq indeterminate. The macros marked with • shall be omitted from [ 

106 <limits.h> dif specific implementations where the corresponding value is | 

106 greater than or equal to the stated minimum, but where the value can vary | 

107 depending on the file to which it is applied. * 

ms <locale.h> 

109 The header defines the macros 1 


110 LC_ALL* LC_CTYPE* LC_NUMERIC* NULL* 

111 LC_COLLATE* LC_MONETARY * LC_TIME* 

112 and declares the structure 

113 Iconv * 


114 with structure elements 

116 currency _symbol* 

116 decimal_point * 

117 fracjiigits* 

ns grouping * 

119 int_curr_symbol * 

120 int _frac_digits* 

121 and the functions 


monjiecimal _point* 
mon_grouping* 
mon_thousands_sep* 
n_cs _ precedes * 
n_sep_by_space * 
n_sign josn* 


negative _sign* 
p_cs _precedes* 
p_sep_by_space * 
pjsign _posn* 
positive_sign* 
thousands_sep* 


122 localeconvO* setlocaleO * 


ISOflEC 9946-1: 1990 
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123 <math . h> 

124 The header defines the macro 

125 HUGE_VAL 

126 and declares the functions 


127 

acos () 

ceili) 

exp() 

fmod() 

log 10 () 

pow () 

sqrti) 

128 

asin () 

cos () 

fabsO 

frexpi) 

log 0 

sini) 

tani) 

129 

atan 2 () 

cosh() 

floori) 

IdexpO 

modfl) 

sinh() 

tanh() 


wo atan () 

131 <pwd.h> 

132 The header defines the structure 

* 

133 passwd *" 

% 

134 with structure elements 

135 pw_dir pw_gid pwjmme pwjshell pw_uid 

136 and declares the functions 

137 getpwnamO getpwuidO 

138 <SBtjmp.h> 

139 The header defines the types 

no jmp_buf sigjmp_buf 

141 and declares the functions 

142 longjmp () setjmpO siglongjmpO sigsetjmpO 

143 Note that the C Standard (2) and this part of ISO/IEC 9945 both permit these 

144 functions to be defined solely as macros. 

145 <signal.h> 

146 The header defines the macros 


147 

SA_NOCLDSTOP 

SIGHUP 

SIGQUIT 

SIGTTIN 

SIG_DFL 

148 

SIGABRT 

SIGILL 

SIGSEGV 

SIGTTOU 

SIG_ERR* 

149 

SIGALRM 

SIGINT 

SIGSTOP 

SIGUSR1 

SIG_IGN 

160 

SIGCHLD 

SIGKILL 

SIGTERM 

SIGUSR2 

SIG_SETMASK 

161 

SIGCONT 

SIGPIPE 

SIGTSTP 

SIG_BLOCK 

SIG_UNBLOCK 

162 

SIGFPE 






163 and the types 


I 
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sig_atomic_t * sigsetj 

and declares the structure 
sigaction 

with structure elements 

sa Jlags sa handler sa_mask 

and the functions 

killO sigaddsetO sigfillsetO sigpendingi) 

raise ()* sigdelseti) sigismemberO sigprocmaskO 

sigactionO sigemptysetO signalO * sigsuspendO 

<stdarg.h>« 

The header defines the macros 

vajxrg * va_end * vajist * va_start* 

<stddef .h>* 

The header defines the macros 
NULL* offsetof* 

and the types 

ptrdiffj * sizej* uicharj* 

<stdio .h> 

The header defines the macros 

BUFSIZ L_tmpnam* STREAM_MAX* stdout 

EOF NULL TMP_MAX _IOFBF* 

FILENAME_MAX* SEEK_CUR stderr _IOLBF* 

L_ctermid SEER_END stdin _IONBF* 

L_cuserid SEEK^SET 

NOTE: The L_cuserid symbol is permitted in this header, but need not be supplied. See 2.7.2. 
and the types 

fposj* sizej 
and declares the type 


h 


x 
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182 FILE 


183 and the functions 


184 

clearerri ) 

filenoO 

fsetpos ()* 

putchari, ) 

sprintfO 

185 

fclose () 

fopenO 

ftelU) 

puts() 

sscanfl ) 

186 

fdopenO 

fprintfi ) 

fwritei) 

remove 0 

tmpfileO 

187 

feofi ) 

fputcO 

getc() 

renamed ) 

tmpnamO 

188 

ferrori ) 

fputsO 

getcharO 

rewindO 

ungetcO 

189 

fflushO 

freadO 

getsO 

scanfO 

v fprintfi)* 

190 

fgetcO 

freopenO 

perrori ) 

setbufl ) 

vprintfi )* 

191 

fgetposO* 

fscanfl ) 

printfO 

setvbufX )* 

vsprintfl )* 

192 

fgetsO 

fseek 0 

putcO 




193 <stdlib.h> 

194 The header defines the macros 


195 EXIT_FAILURE MB_CUR_MAX* RAND_MAX 

196 EXIT_SUCCESS NULL 

197 and the types 

198 divj* IdivJ* sizej wcharj* 

199 and declares the functions 

200 abortO bsearchi.) labsO* qsorti) strtolO* 

201 absi) callocO Idiv 0* randO strtoulO* 

202 atexitO* div ()* mallocO reallocO systemO* 

203 atofX) exit() mblenO* srandO wcstombsO* 

204 atoiO freeO mbstowcsO* strtodO* wctombO * 

205 atoU) getenvO mbtowcO * 

206 <string.h> 

207 The header defines the macro 

208 NULL 

209 and the type 

210 sizej 
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211 

and declares the functions 





1 

241 

212 

memchrO* strcatO 

strcspn () 

strncmpO 

strspnO 

1 


213 

memcmpO * strchr () 

strerrorO* 

strncpyO 

strstri ) 

1 

242 

214 

memcpy ( )* strcmpO 

strlenO 

strpbrkO 

strtok 0 

1 

243 

215 

memmove 0* strcollO* 

strncatO 

strrchri ) 

strxfrmO* 

1 


216 

memsetO* strcpyO 





1 

244 








245 

217 

<sy3/stat .h> 





1 


218 

The header defines the macros 





1 

246 

219 

SJRGRP SJRWXO 

SJSCHR 

S_ISG1D 

S_IWGRP 

SJXGRP 


247 

220 

S 1ROTH S_IRWXU 

S_ISDIR 

SJSREG 

S_IWOTH 

SJXOTH 



221 

SJRUSR SJSBLK 

SJSFIFO 

S_ISU1D 

SJWUSR 

SJXUSR 

1 

248 

222 

SJRWXG 





1 

249 

223 

and declares the structure 





1 

260 

224 

stat 





1 

251 

225 

with structure elements 





1 

252 

226 

stjitime stjdev 

stjno 

stjntime 

st_size 


1 

253 

227 

stjctime stj>id 

stjnode 

stjilink 

st_uid 


1 

254 

220 

' and the functions 





|‘ 

266 

229 

chmodO mkdirO stat () 




1 

256 

230 

fstatO mkfifoO umaski) 




1 








267 

231 

<sys/times ,h> 





1 

258 

232 

The header defines the type 





1 

259 

233 

clockjt 





1 

260 








261 

234 

and declares the structure 





1 

262 








263 

235 

tms 





1 

264 








265 

236 

with structure elements 





1 

266 








267 

237 

tms _cs time tmsjcutime tms _s time tms _u time 


1 

268 








269 

238 

and the function 





1 

270 








271 

239 

times () 





1 

272 


<sys/types -h> 

The header defines the types 

devj inoj nlinkj pidj ssizej 

gidj modej offj sizej uidj 

Oys/utsname .h> 

The header declares the structure 


utsname 

with structure elements 


machine nodename release sysname version 

and the function 

uname () 

<sys/wait .h> 

The header defines the macros 

WEXITSTATUS W1FSIGNALED WNOHANG WTERMSIG 

WIFEXITED WIFSTOPPED WSTOPSIG WUNTRACED 


and declares the functions 

uiaitO waitpidO 


<termios .h> 

The header defines the macros 


BO 

B110 

B1200 

B134 

B150 

B1800 

B19200 

B200 

B2400 

B300 

B38400 

B4800 

B50 

B600 


B75 

B9600 

BRKINT 

CLOCAL 

CREAD 

CS5 

CS6 

CS7 

CS8 

CSIZE 

CSTOPB 

ECHO 

ECHOE 

ECHOK 


ECHONL 

HUPCL 

1C ANON 

ICRNL 

IEXTEN 

IGNBRK 

IGNCR 

IGNPAR 

1NLCR 

INPCK 

IS1G 

ISTRIP 

IXOFF 

IXON 


NCCS 

NOFLSH 

OPOST 

PARENB 

PARMRK 

PARODD 

TCIFLUSH 

TCIOFF 

TCIOFLUSH 

TC10N 

TCOFLUSH 

TCOOFF 

TCOON 

TCSADRAIN 


TCSAFLUSH 

TCSANOW 

TOSTOP 

VEOF 

VEOL 

VERASE 

V1NTR 

VKILL 

VMIN 

VQUIT 

VST ART 

VSTOP 

VSUSP 

VTIME 
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273 and the types 

274 ccj speed J tcflagj 

275 and declares the structure 

276 termios 

277 with structure elements 

278 c_cc c_cflag cjflag cjflag c_oflag 

279 and the functions 

280 cfgetispeedO cfsetospeedO tcflushO tcsendbreakO 

281 cfgetospeedO tcdrainO tcgetattrO tcsetattrO 

282 cfsetispeedO tcflowQ 

283 <time.h> 

284 The header defines the macros 

285 CLKJTCK ^ CLOCKS_PER_SEC NULL 

286 the types 

287 clockj sizejt timej 

288 and declares the structure 

289 tm 

290 with structure elements 

291 tmjiour tm_mday tmjnon tmjuuday tm_year 

292 tmjsdst tm_min tm_sec tm _yday 

293 and the functions 

294 asctime 0 dime 0 gmtime 0 mktime () timed 

295 clock ()* difftime ()* localtime () strftime () tzset () 

296 and declares the external variable 

297 tzname 


I' 
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298 <unistd.h> 

299 The header defines the macros 

300 F_OK 

301 NULL 

302 R OK 

303 SEEK_CUR 

304 SEEK_END 

305 SEEK.SET 

306 STDERRJFILENO 

307 STD1N_FILEN0 

308 STDOUT_FILENO 

309 W_OK 

310 X_OK 

311 _PC_CHOWN_RESTRICTED 

312 _PC_LINK_MAX 

313 _PC_MAX_CANON 

314 _PC_MAX_INPUT 

315 _PC_NAME_MAX 

316 _PC_NO_TRUNC 

317 _PC_PATH_MAX 

318 and defines the types 

319 size_t* ssizej » 

320 and declares the functions 


_PC_PIPE_BUF 
_PC_VDISABLE 
_POSIX_CHOWN_RESTRICTED 
_POSIX_JOB_CONTROL 
_POSI)d.NO_TRUNC 
_P0SIX^SAVED_1DS 
_P0S1X_VD1SABLE 
_POSIX_VERSION 
_SC_ARG_MAX 
_SC_CHILD_MAX 
_SC_C LK_TC K 
_SC_JOB_CONTROL 
_SC_NGROUPS_MAX 
_SC_OPEN_MAX 
‘ _SC_SAVED_IDS 
_SC_STREAM_MAX 
_SC_TZNAME_MAX 
_SC_VERS10N 


setsidi ) 
setuidO 
sleep 0 
sysconfi) 
tcgetpgrp(') 
tcsetpgrpO 
ttyname 0 
unlink 0 
writeO 


331 NOTE: The cuseridO symbol is permitted in this header, but need not be supplied. See 2.7.2. 

332 <utime.h> 

333 The header declares the structure 


321 

_exit() 

execli ) 

geteuidO 

link 0 

322 

access () 

erected 

getgidO 

Iseek () 

323 

alarm {) 

exec Ip 0 

getgroupsO 

pathconfX ) 

324 

chdir ( ) 

execvO 

getloginO 

pause 0 

325 

chowni) 

execveO 

getpgrpO 

pipe 0 

326 

close 0 

execvpO 

getpidO 

read ( ) 

327 

ctermidO 

fork () 

getppidO 

rmdirO 

328 

cuseridO 

fpathconfO 

getuidO 

setgidO 

329 

dup20 

getcwdO 

isattyO 

setpgidO 

330 

dupO 

getegidi ) 




334 utimbuf 

335 with structure elements 
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actime modtime 


337 and the function 


utime () 
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Annex D 

(informative) 

Profiles 


This standard contains a number of options and variables that reflect the range of 
systems and environments that might be encountered. In general, it will be use- 
ful for applications to take the full range of these possibilities into account and 
either accommodate them or exclude them. However, there are significant com.' 
munities of interest that may hqve common needs that warrant focusing on a 
specific suite of these options and parameters. This annex discusses the concept 
of profiles (also known as functional standards) and how they address this 
problem. 

This annex reflects current thinking. It is clear that a concept such as this will 
help significantly in clarifying the intended use of these standards. It is to be 
expected that some of the details of this material will be changed before it is fully 
stabilized. 

As background: the OSI model has over 170 standards (and consequent combina- 
tions thereof) that fit within it. Only a fraction of those are actually useful for any 
given application environment. The concept of profiles was developed to address 
this issue and appears also to apply to the area of application portability. The 
ISO/IEC term for such profiles is ISP, or “International Standardized Profile.” 


ib D.l Definitions 

19 The following definitions are proposed for use in the area covered by this part of 

20 ISO/IEC 9945. 

21 D.1.1 Applications Environment Profile (AEP) [profile]: The specification of 

22 a complete and coherent subset of an Open System Environment, together with 

23 the options and parameters necessary to support a class of applications for intero- 

24 perability or applications portability, including consistency of data access and 

25 human interfaces. Where there are several AEPs for the same OSE, they are har- 

26 monized. 

27 AEPs are the basis for procurement and conformance testing and are the target 

28 environment for software development. 

29 D.1.2 Application Specific Environment (ASE): A complete and coherent 

30 subset of an Applications Environment Profile, together with interfaces, services, 

31 or supporting formats outside of the profile, that are required by a particular 
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application for its installation and execution. 

D.X.3 Application Specific Environment Description (ASED): The 
specification of an Application Specific Environment, together with the specific 
options or parameters required; interfaces, services, or supporting formats outside 
of the profile; and resource requirements necessary for the satisfactory operation 
of the application. (For example, storage and performance requirements.) 

(This term is intended for use in Applications Conformance clauses found in 
profiles.) 

D.1.4 coherent: The parts are logically connected. (For example, if both FOR- 
TRAN and COBOL are specified, whether they can share files is specified.) 

D.1.5 complete: Having all the necessary parts. (For example, if COBOL and 
SQL are both specified, then there is a COBOL binding to SQL, or at least an expla- 
nation of why not.) 

D.1.6 comprehensive: A sufficiently broad range of functionality is covered 
that the needs of most Applications Environment Profiles are met. 

D.1.7 consistent: The parts of the Open System Environment do not inherently 
conflict with each'«ther. This does not preclude options that conflict, as long as 
an Applications Environment Profile can select a set that does not conflict. 

D.1.8 harmonized: Where same functionality is needed in several profiles, it 
appears identically in all of them. 

D.1.9 Open System Environment (OSE): A comprehensive and consistent set 
of international information technology standards and functional standards 
(profiles) that specify interfaces, services, and supporting formats to accomplish 
interoperability and portability of applications, data, and people. These are based 
on International Standards (ISO, IEC, CCITT, . . . ) 

D.1.10 POSIX Open System Environment: A comprehensive and consistent 
set of ISO/IEC, regional, and national information technology standards and func- 
tional standards (profiles) that specify interfaces, services, and supporting for- 
mats for interoperability and portability of applications, data, and people that are 
in accord with ISO/IEC 9945 (POSIX). 

No single component of the OSE, including ISO/IEC 9945, is expected to be 
required in all such profiles. 




«4 D.2 Options in This Part of ISO/IEC 9945 

65 In terms of this part of ISO/IEC 9945, there are a number of features that could be 

66 specified in a profile. This list includes: 

67 — The options listed in 1.3. 1.3. 

68 — The limits in 2.8. Regarding the the C Language Limits for the type char, 

69 care should be taken that those limits are not for the POSIX.l definition of 

70 character, but for the one in the C language. For the POSIX.1 definition of 
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character, the following limits from the C Standard (2) could be specified as 
well: (MB_LEN_MAX) and (MB_CUR_MAX). 

The flags in 2.9.4. 

Instances of the word “may" throughout the document. (Note that not all 
instances of “may” constitute behavior that could or should be considered 
appropriate for specification in a profile. Some reflect implementation vari- 
ants that should not matter to applications.) 

■ Features that are specified in a generic way for broad portability of the 
standard, that might reasonably be constrained in the more limited context 
of a profile. For such features, the constraint shall be documented in a 
profile so that the effects of the constraint on the standard would be 
clarified. 


D.3 Related Standards 

The other POSIX standards (ISO/IEC 9945-2 (B36), in particular) are expected to 
form a major part of the POSIX OSE. Other formal standards, such as those listed 
in Annex A, are also expected to be part of such a document (in particular, the 
C Standard (2).) 

Standards such as other languages, SQL, graphics standards such as GKS, and 
networking standards are also probable candidates for inclusion in the POSIX 
OSE. 


D.4 Related Activities 

In many ways, the work of NIST (in terms of FIPS), OSF, UNIX International, and 
X/Open often act like early (but sophisticated) profiles or metaprofiles, specifying 
a range of standards from which true profiles could select. They collect together 
many standards, specify options, and specify the relationship between the parts. 
These activities go well beyond profiles, as they add specifications that are not for- 
mal standards to the suite as well. Often these additional specifications point to 
areas where formal standards are required. 


D.5 Relationship to IEEE Draft Project 1003.0 I 

The IEEE P1003.0 working group is writing a Guide to Open Systems. In many | 
ways, this is the specification of the POSIX Open Systems Environment. It could | 
be the specification of the collection of standards that might be used to specify | 
many Open Systems Environments, depending on how exactly that work | 
proceeds. ' 
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Annex E I 

(informative) 

Sample National Profile 


1 One class of “community of interest” for which profiles (as discussed in Annex D) | 

2 are useful is specific countries, where the general characteristics warrant specific j 

3 focus to serve the needs of users in those countries. Such needs lead to a number 

4 of implications concerning the options available within this part of ISO/IEC 9945^* 

5 and may warrant specification of complementary standards as well. . 

6 The following is an example of a country’s needs with respect to this part of | 

7 ISO/IEC 9945 and how those needs relate to other international standards as well | 

s as national standards. The example provided is included here for informative | 

9 purposes and is not a formal standard in the country in question. It is provided j 

10 by the Danish Standards Association and is as accurate as possible with regards 

u to Danish needs. 11 This example national profile is worded as if it were a national 

12 standard. 1 

13 A subclass of conforming implementations can be identified that meet the require- | 

14 ments of a specific profile. By documenting these either in national standards, in | 

16 a document similar to an ISO/IEC ISP (an International Standardized Profile), or | 

is in an informative annex (such as this), these can be referenced in a consistent 

17 manner. 


18 1) Further information may be obtained from the Danish Standards Association, Attn: S142u22All 

19 POSH WG, Box 77, DK-2900 Hellerup, Denmark; FAX: +45 31 62 30 77; Email: poolx@itc.dk 

20 The data is also available electronically by anonymous FTAM or FTP at the site dkuug . dk in the 

21 directory isp, where some other example national profiles, locales, and charmapa may also be 

22 found. They are also available by an archive server reached at archlve@dkuug.dk; use 

23 “Subject: help” for further information. 

24 More complete examples of profiles are expected to be available in future revisions of this part of 

26 ISO/IEC 9945 and in other POSIX standards. 
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26 E.l (Example) Profile for Denmark | 

27 NOTE: This profile is chosen both for its instructive value by being a European profile and the gen- 

28 erality in the provisions it makes, addressing most of the relevant points. It does claim to be correct 

29 for Denmark, and the style is what would be expected in a real ISP. A collection of real ISPs would 

30 be as useful, and work is underway collecting these. 

31 This is the definition of the Danish Standards Association POSIX. 1 profile. Infor- | 

32 mation on the actual data for the locale and coded character set mapping | 

33 definitions are under development as part of an informative annex in j 

34 ISO/IEC 9945-2 (B36}. 2) j 

35 The subset of conforming implementations that provide the required characteris- | 

36 tics below is referred to as conforming to the “Danish Standards Association (DS) j 

37 Environment Profile” for this part of ISO/IEC 9945. 

38 The profile specifies no options according to POSIX.1 section 2.9.3. For section | 

39 2.8.4 in the <limits.h> specification, the LPOSIXJTZNAME_MAX) value shall | 

40 be 7. I 


E.1.1 Character Encoding 

Any character enco<}Wig with the required repertoire of the POSIX profile plus the 
following repertoire shall be allowed. 

A “character set description file,” as described in ISO/IEC 9945-2, (B36) shall use 
the symbolic character names of the iso_10646 charmap file described in the 
ISO/IEC 9945-2 {B36} sample profile annex for the characters encoded in the char- 
acter set. 

For the Danish and Greenlandic languages, the following characters shall be 
present in addition to the repertoire required by the POSIX profile: <ae>, <o/>, 
<aa>, <ae>, <0/>, and <aa>. For the Faroese language, the following characters 
shall be present in addition to the required POSIX locale characters and Danish 
repertoire: <a'>, <i'>, <o'>, <u'>, <y'>, <d->, <A'>, <I'>, <0'>, <U'>, 
<Y' >, and <D->. 

Recommended character sets are ISO 8859-1 {B34} or ISO 10646 {B37}. The 
CHARSET environment variable shall be used to specify the processing character 
set; for instance, iso_8859-l or iso_10646. This shall be used to select the 
encoded character-set-specific versions of the locale definitions. If no CHARSET 
variable is present, iso_8859-l shall be assumed. 


59 2) The 9945-2 document, "POSIX.2,” is currently in the state of a Committee Document (CD), to be 

60 approved as a Draft International Standard. 
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61 E.1.2 Character Encoding and Display 

62 For terminal equipment not capable of generating or showing the processing char- 

63 acter set, the character names defined in the current charmap file shall be used: 

64 characters in the charmap file having two-character names shall be specified by 

65 the two-character name preceded by the <intro> character, and characters hav- 

66 ing charmap names longer than two characters shall be specified by the character 

67 name preceded by the <intro> character and an <underline> and followed by 

68 an <underline>. In names longer than two characters, an <intro> character 

69 and an <underline> character in sequence shall signify a literal <underline> 

70 character part of the character name. Two <intro> characters in sequence shall 

71 signify one <intro> character, both in names and in the general stream. 

72 For input, if the character name is undefined in the current charmap file, the data 

73 shall be left untouched (including the <intro> character) and the behavior is 

74 implementation defined. ^ 

*r 

75 E.l. 3 Locale Definitions * 

76 The following guideline is used for specifying the locale identification string: 3 * 

77 " % 2 . 2 s_% 2.2s.%s,%s", <language>, <territory>, <character-set>, 

78 <version> 

79 where <language> shall be taken from ISO 639 (B32) and <territory> shall be the 

so two-letter country code of ISO 3166 (B33), if possible. The <language> shall be 

si specified with lowercase letters only, and the <territory> shall be specified in 

82 uppercase letters only. An optional <character-set> specification may follow after 

83 a <period> for the name of the character set; if just a numeric specification is 

84 present, this shall represent the number of the international standard describing 

85 the character set. If the <character-set> specification is not present, the encoded 

86 character set specific locale shall be determined by the CHARSET environment 

87 variable, and if this is unset or null, the encoding of ISO 8859-1 (B34) shall be 

88 assumed. A parameter specifying a <version> of the profile may be placed after 

89 the optional <character-set> specification, delimited by <comma>. This may be 

90 used to discriminate between different cultural needs; for instance, dictionary 

91 order versus a more systems-oriented collating order. 

92 Following the above guidelines for locale names, the national Danish locale string 

93 shall be 

94 da_DK 

95 In the following, the TZ variable shall be specified according to the current official 

96 daylight-saving-time rules in Denmark. Since Daylight Saving Time is politically 

97 decided and thus changeable, this is only a recommendation. 


3) The guideline was inspired by the XI Open Portability Guide (B61). It is presented in the file 
format notation used by ISO/IEC 9945-2 (B36). 


E. 1 (Example) Profile for Denmark 



'l 
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Identifier Index 


abortO 

abs 0 

access () 

acos () 

alarmO 

asctimeO 

asinO 

assertO 

atanO 

atan2() 

atofO 

atoiO 

atolV) 

bsearchO 

callocl) 

ceilO 

cfgetispeedO 

cfgetospeedO 

cfsetispeedl ) 

cfsetospeedl) 

chdirO 

chmodO 

chownO 

clearerr( ) 

close () 

closedirO 

cos 0 

coshO 

cpio 

creatO 

ctermidO 

ctimeO 

devj 

directory 

<dirent . h> 

dup () 

dup2() 

environ 

errno 

<errno . h> 

exec 

execll ) 

execlel ) 

execlpO 

execv () 

execveO 


Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Check File Accessibility (5.6.3) 104 

Referenced C Language Routines (8.1) 151 

Schedule Alarm (3.4.1) 63 

Extensions to Time Functions (8.1.1) 152 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 ^ 

Referenced C Language Routines (8.1) 151*. 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Baud Rate Functions (7.1.3) 141 

Baud Rate Functions (7.1.3) 141 

Baud Rate Functions (7.1.3) 141 

Baud Rate Functions (7.1.3) 141 

Change Current Working Directory (5.2.1) 86 

Change File Modes (5.6.4) 106 

Change Owner and Group of a File (5.6.5) 107 

Referenced C Language Routines (8.1) 151 

Close a File (6.3.1) H5 

Directory Operations (5.1.2) 83 

Referenced C Language Routines (8.1) 151 

Referenced C Language Routines (8.1) 151 

Extended cpio Format (10.1.2) 173 

Create a New File or Rewrite an Existing One (5.3.2) 91 

Generate Terminal Pathname (4.7.1) 78 

Referenced C Language Routines (8.1) 152 

Primitive System Data Types (2.5) 27 

Directory Operations (5.1.2) 83 

Format of Directory Entries (5.1.1) 83 

Duplicate an Open File Descriptor (6.2.1) 114 

Duplicate an Open File Descriptor (6.2.1) 114 

Execute a File (3.1.2) 42 

Error Numbers (2.4) 23 

Error Numbers (2.4) 23 

Execute a File (3.1.2) 42 

Execute a File (3.1.2) 42 

Execute a File (3.1.2) 42 

Execute a File (3.1.2) 42 

Execute a File (3.1.2) 42 

Execute a File (3.1.2) 42 
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execvp () 

exit ( ) 

_exit() 

exp() 

fabs() 

/close ( ) 

fcntK) 

<fcntl . h> 

fdopenO 

feofO 

ferrorl ) 

fflushO 

fgetcO 

fgetsO 

filenoO 

floorO 

fmodO 

fopenO 

fork () 

fpalhconfO 

/print f ( ) 

fputcO 

fputsO 

freadO 

/reel) 

/reopen () 

frexpi) 

fscanfl ) 

/seek () 

fstati ) 

ftellO 

fuirileO 

getcO 

getchar( ) 

getcwdO 

getegidO 

getenu() 

geteuidO 

getgidO 


getgrgidO 

getgrnamO 

getgroupsO 

getloginO 

getpgrpO 

getpidO 

getppidO 

getpumamO 

getpwuidO 


Execute a File (3.1.2) 

Referenced C Language Routines (8.1) 

Terminate a Process (3.2.2) ■ 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

File Control (6.5.2) 

Data Definitions for File Control Operations (6.5.1) 

Open a Stream on a File Descriptor (8.2.2) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) ZZZZZ. 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Map a Stream Pointer to a File Descriptor (8.2.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Process Creation (3.1.1) 

Get Configurable Pathname Variables (5.7.1) 

Referenced C Language Routines (8.1) 

t !Referenced C Language Routines (8.1) "... 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) ZZZZ. 

Referenced C Language Routines (8.1) 

Get File Status (5.6.2) "" 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) 

Referenced C Language Routines (8.1) ZZZ.Z. 

Referenced C Language Routines (8.1) 

Get Working Directory Pathname (5.2.2) 

Get Real User, Effective User, Real Group, and Effective 

Group IDs (4.2.1) 

Environment Access (4.6.1) 

Get Real User, Effective User, Real Group, and Effective 

Group IDs (4.2.1) 

Get Real User, Effective User, Real Group, and Effective 

Group IDs (4.2.1) 

Group Database Access (9.2.1) 

Group Database Access (9.2.1) 

Get Supplementary Group IDs (4.2.3) 

Get User Name (4.2.4) 

Get Process Group ID (4.3.1) 

Get Process and Parent Process IDs (4.1.1) 

Get Process and Parent Process IDs (4.1.1) 

User Database Access (9.2.2) ...Z, 

User Database Access (9.2.2) 


... 42 
.. 151 
.. 49 
.. 151 
.. 151 
.. 151 
.. 121 
.. 121 
.. 157 
.. 151 
.. 151 
.. 151 
.. 151 
.. 151 
. 156 
. 151 
. 151 
. 151 
. 41 
. 110 
. 151 
. 151 
. 151 
. 151 
. 151 
. 151 
. 151 
, 151 
151 
103 
151 
151 
151 
151 
87 

68 

77 

68 

68 

166 

166 

70 

71 

72 
67 
67 

167 

167 
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gets() Referenced C Language Routines (8.1) 151 

getuidO Get Real User, Effective User, Real Group, and Effective 

Group IDs (4.2.1) 68 

gidj Primitive System Data Types.(2.5) 27 

gmtime () Referenced C Language Routines (8.1) 152 

<grp.h> Group Database Access (9.2.1) 166 

inoj Primitive System Data Types (2.5) 27 

isalnumO Referenced C Language Routines (8.1) 151 

isalpha 0 Referenced C Language Routines (8.1) 151 

isatty () Determine Terminal Device Name (4.7.2) 79 

iscntrli) Referenced C Language Routines (8.1) 151 

isdigitO Referenced C Language Routines (8.1) 151 

isgraphO Referenced C Language Routines (8.1) 151 

islower() Referenced C Language Routines (8.1) 151 

isprint 0 Referenced C Language Routines (8.1) 151 

ispunctO Referenced C Language Routines (8.1) 151*-'’ 

isspace 0 Referenced C Language Routines (8.1) 151 

isupper() Referenced C Canguage Routines (8.1) 151 

isxdigit () Referenced C Language Routines (8.1) 151 

kill() Send a Signal to a Process (3.3.2) 56 

Idexp () Referenced C Language Routines (8.1) 151 

<limits . h> Numerical Limits (2.8) 34 

link () Link to a File (5.3.4) 92 

localtime () Referenced C Language Routines (8.1) 152 

log() Referenced C Language Routines (8.1) 151 

loglO 0 Referenced C Language Routines (8.1) 151 

longjmpO Referenced C Language Routines (8.1) 151 

Iseek () Reposition Read/Write File Offset (6.5.3) 127 

mainO Description (3. 1.2.2) 43 

malloc () Referenced C Language Routines (8.1) 151 

mkdir ( ) Make a Directory (5.4.1) 94 

mkfi/oO Make a FIFO Special File (5.4.2) ZZZZZZZZZZZ 95 

mktime () Referenced C Language Routines (8.1) 152 

mode_t Primitive System Data Types (2.5) 27 

modfl) Referenced C Language Routines (8.1) 151 

nlinkjt Primitive System Data Types (2.5) 27 

offj Primitive System Data Types (2.5) 27 

openO Open a File (5.3.1) ZZZZ. 88 

opendirO Directory Operations (5.1.2) 83 

pathconfO Get Configurable Pathname Variables (5.7.1) 110 

pause () Suspend Process Execution (3.4.2) 64 

perrorO Referenced C Language Routines (8.1) 151 

pid_t Primitive System Data Types (2.5) 27 

pipeO Create an Inter-Process Channel (6.1.1) 113 

POUiO Referenced C Language Routines (8.1) 151 

printfO Referenced C Language Routines (8.1) 151 

putcO Referenced C Language Routines (8.1) 151 

putchar () Referenced C Language Routines (8.1) 151 

putsO Referenced C Language Routines (8.1) 151 

<pwd.h> User Database Access (9.2.2) 167 

qsortO Referenced C Language Routines (8.1) 151 
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randO Referenced C Language Routines (8.1) 151 

read() Read from a File (6.4.1) 116 

readdiri.) Directory Operations (5.1.2) i 83 

realloc () Referenced C Language Routines (8.1) 151 

remove () Referenced C Language Routines (8.1) 151 

rename () Rename a File (5.5.3) 99 

rewindO Referenced C Language Routines (8.1) 151 

rewinddirO Directory Operations (5.1.2) 83 

rmdirO Remove a Directory (5.5.2) 98 

scanf() Referenced C Language Routines (8.1) 151 

setbufO Referenced C Language Routines (8.1) 151 

setgidO Set User and Group IDs (4.2.2) 68 

setjmp () Referenced C Language Routines (8.1) 151 

setlocale () Extensions to setlocaleO Function (8.1.2) 154 

setpgidO Set Process Group ID for Job Control (4.3.3) 73 

setsidO Create Session and Set Process Group ID (4.3.2) 72 

setuidO Set User and Group IDs (4.2.2) 68 

sigactioni) Examine and Change Signal Action (3.3.4) 58 

sigaddseti ) Manipulate Signal Sets (3.3.3) 57 

sigdelseti ) Manipulate Signal Sets (3.3.3) 57 

sigemptyseti ) Manipulate Signal Sets (3.3.3) 57 

sigfillsetO ^Manipulate Signal Sets (3.3.3) 57 

sigismemberO Manipulate Signal Sets (3.3.3) 57 

siglongjmpO Nonlocal Jumps (8.3.1) 162 

<slgnal.h> Signal Concepts (3.3.1) 51 

sigpending () Examine Pending Signals (3.3.6) 62 * 

sigprocmask () Examine and Change Blocked Signals (3.3.5) 60 

sigsetjmpO Nonlocal Jumps (8.3.1) 162 

sigsetops Manipulate Signal Sets (3.3.3) 57 

sigsuspendO Wait for a Signal (3.3.7) 62 

sin() Referenced C Language Routines (8.1) 151 

sinh() Referenced C Language Routines (8.1) 151 

sizej Primitive System Data Types (2.5) 27 

sleep () Delay Process Execution (3.4.3) 65 

sprintfi) Referenced C Language Routines (8.1) 151 

sqrt() Referenced C Language Routines (8. 1) 151 

srand () Referenced C Language Routines (8. 1) 151 

sscanfl ) Referenced C Language Routines (8.1) 151 

ssize_t Primitive System Data Types (2.5) 27 

statO Get File Status (5.6.2) 103 

strcat () Referenced C Language Routines (8.1) 151 

strchrO Referenced C Language Routines (8.1) 151 

strcmp () Referenced C Language Routines (8.1) 151 

strcpy () Referenced C Language Routines (8.1) 151 

strcspn () Referenced C Language Routines (8.1) 151 

strftimeO Referenced C Language Routines (8.1) 152 

strlen() Referenced C Language Routines (8.1) 151 

strncatO Referenced C Language Routines (8.1) 151 

strncmp () Referenced C Language Routines (8.1) 151 

strncpy () Referenced C Language Routines (8.1) 151 

strpbrk () Referenced C Language Routines (8.1) 151 
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strrchrO Referenced C Language Routines (8.1) 151 

strspn () Referenced C Language Routines (8.1) 151 

strstrO Referenced C Language Routines (8.1) 151 

strtok 0 Referenced C Language Routines (8.1) 151 

sysconfi) Get Configurable System Variables (4.8.1) 80 

<sys/stat .h> File Characteristics: Header and Data Structure (5.6.1) ... 101 

<sys/times .h> Get Process Times (4.5.2) 76 

<sys/types .h> Primitive System Data Types (2.5) 27 

<3ys/ut3name . h> Get System Name (4.4.1) 74 

<sys/wait.h> Wait for Process Termination (3.2.1) 47 

tan() Referenced C Language Routines (8.1) 151 

tanh() Referenced C Language Routines (8.1) 151 

tar Extended tar Format (10.1.1) 169 

tcdrainQ Line Control Functions (7.2.2) 145 

tcflowO Line Control Functions (7.2.2) 145 

tcflushO Line Control Functions (7.2.2) ■ 145 v 

tcgetattrO Get and Set State (7.2.1) 143 

tcgetpgrpO Get Foreground Process Group ID (7.2.3) 147 

tcsendbreak () Line Control Functions (7.2.2) 145 

tcsetattrl) Get and Set State (7.2.1) 143 

tcsetpgrpO Set Foreground Process Group ID (7.2.4) 148 

termios General Terminal Interface (7.1) 129 

<termio3.h> Parameters That Can Be Set (7.1.2) 135 

time () Get System Time (4.5.1) 75 

timesO Get Process Times (4.5.2) 76 

timej Primitive System Data Types (2.5) 27 

tmpfile () Referenced C Language Routines (8.1) 151 

tmpnamO Referenced C Language Routines (8.1) 151 

tolowerO Referenced C Language Routines (8.1) 151 

toupper () Referenced C Language Routines (8.1) 151 

ttyname () Determine Terminal Device Name (4.7.2) 79 

tzsetO Set Time Zone (8.3.2) 162 

uidj Primitive System Data Types (2.5) 27 

umask () Set File Creation Mask (5.3.3) 91 

uname () Get System Name (4.4.1) 74 

ungetcO Referenced C Language Routines (8.1) 151 

<unistd . h> Symbolic Constants (2.9) 37 

unlink () Remove Directory Entries (5.5.1) 96 

utimeO Set File Access and Modification Times (5.6.6) 108 

wait Wait for Process Termination (3.2.1) 47 

waitpidl) Wait for Process Termination (3.2.1) 47 

write () Write to a File (6.4.2) 118 
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A 

Abbreviations ... 20, 208 
abort() ... 46, 168, 160-161, 291, 307 
definition of ... 151 
rationale . . . 291 
a6s() ... 307 

definition of ... 161 
absolute pathname 
definition of ... 11 
access control lists . . . 209 
access mode 

definition of ... 11 
access () ... 37, 104-105, 208, 261, 311 
definition of ... 104 
rationale . . . 261 
symbolic constants ... 37 
acos () ... 305 

definition of ... 151 
actime . . . 109, 312 
address space 

definition of ... 11 

AEP (see Applications Environment Profile) 
alarm 

schedule ... 63 

alarmi) ... 42,46,63-66,241,244-246,272, 
311 

definition of ... 63 
rationale . . . 244 
ANSI ... 300 

Application Conformance ... 4,192 
Application Specific Environment (ASE) 
definition of ... 313 

Application Specific Environment Description 
(ASED) 

definition of ... 314 
Applications Environment Profile (AEP) 
Tprofile] 

definition of ... 313 

appropriate privileges ... 17, 21, 26, 39, 56, 
69-70, 92-93, 97, 105-111, 169, 172, 176- 
177, 199, 208, 246-247, 261 
definition of ... 11 
rationale . . . 199 

Archive/Interchange File Format . . . 169, 294 
|ARG_MAX) ... 24,29,44-45,80,230,304 
definition of ... 36 


array of char 

definition of ... 29 
ASCH ... 207 
aactimeO ... 310 

definition of ... 152 

ASED (see Application Specific Environment 
Description) 
aain() ... 305 

definition of ... 151 
_aBm_builtin_atoi() ... 195 y 

assertO ... 301 *“ 

definition of ... 161 
<assert.h> ... 301 
asynchronous I/O . . . 289 
atan2( ) ... 305 

definition of ... 151 
atan() ... 305 

definition of ... 151 
atexitO ... 189,232,307 
atof{ ) ... 307 

definition of ... 151 
atoi() ... 194-195,307 
definition of ... 161 
atol{) ... 307 

definition of ... 151 

B 

background process group 
definition of ... 12 
background process 
definition of ... 12 

background ... 12,15,51,118,121,130-131, 
139, 143, 147, 202-204, 206, 248, 277-278, 
281-282 

Base by POSDC.1, Additions by the C Standard 
... 188 

Base by the C Standard 

Additions by POSDC.1 ... 188 
Baud Rate Functions . . . 141, 281 
Baud Rate Values . . . 141, 281 
Bibliography ... 179 
binary stream . . . 152 
block special file 

definition of ... 12 
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blocked signals ... 60 
brk() ... 188,292 

rationale for omission . . . 292 
BRKINT ... 136 

BSD ... 199,202,205-207,209,213-214,216, 

222, 231-234, 236-239, 241-244, 247-250, 
253, 258-260, 262-264, 266, 270, 272-273, 
276-278, 282-284, 287, 291, 294, 296 
signals . . . 234 

bsearchO ... 188,307 
definition of ... 151 
By Neither POSIX. 1 Nor the C Standard 
... 188 

byte 

definition of ... 29 

Byte-Oriented cpio Archive Entry ... 174 

c 

C Language Definitions ... 29, 217 
C Language Input/Output Functions . . . 155, 
287 

C Language Limits . ..tfjlf, 223 
C language 

FILE functions ... 158 
input/output functions . . . 155 
language-dependent services ... 5 
related specifications ... 6 
C locale ... 154-155,286 
C Shell ... 202-204,216 
C Standard Language-Dependent Support 
... 32 

C Standard Language-Dependent System Sup- 
port ... 5, 194 

C Standard ... 2, 5-7, 12, 20, 24, 26-27, 29-30, 
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University of South Florida » 
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University of Tennessee 

University of Texas at Arlington 

University of Texas at Austin 

University of Toronto 

University of Utah 
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UNIX/WORLD 

US Air Force 
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US Department of H.U.D. t 
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West Virginia University 
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World UNIX & C 
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In the preceding list, the organizations marked with an asterisk (*) have hosted 
1003 Working Group meetings since the group’s inception in 1985, providing use- 
ful logistical support for the ongoing work of the committees. 
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Table 6-1 - cmd Values for fcntlO 


310 

Constant 

Description 

311 

312 

313 

314 

316 

316 

317 

318 

319 _ 

f.dupfd 

f.getfd 

f_getlk 

F_SETFD 

f.getfl 

F.SETPL 

f.setlk 

F_setucw 

Duplicate file descriptor. 

Get file > ! v vriptor flags. 

Getrec.. - king information. 

Set file descriptor flags. 

Get file status flags. 

Set file status flags. 

Set record locking information. 

Set record locking information; wait if blocked. 

320 

321 _ 

Table 6-2 - File Descriptor Flags Used tor fcntlO 

322 

Constant 

Description 

323 

324 

326 _ 

FD_CLOEXEC 

Close the file descriptor upon execution of an exec-family 
function. 

326 

327 

Table 6-3 

- Ltype Values for Record Locking With fcntlO 

328 

Constant 

Description 

329 

330 

331 

332 

f.rdlck 

f_unlck 

f.wrlck 

Shared or read lock. 

Unlock. 

Exclusive or write lock. 

333 

334 _ 


Table 6-4 - oflag Values for open ( ) 

336 

Constant 

Description 

336 

337 

338 

339 

340 

0_CREAT 

o_excl 

O_N0CTTY 

0_TRUNC 

Create file if it does not exist. 

Exclusive use flag. 

Do not assign a controlling terminal. 

Truncate flag. 

341 

342 

Table 6-5 - 

- File Status Flags Used for open () and fcntlO 

343 

Constant 

Description 

344 

346 

346 __ 

0_APPEND 

0_NONBLOCK 

Set append mode. 

No delay. 


347 

S-6 - 

File Access Modes Used for open ( ) and fcntl ( ) 

349 

.ant 

Description 

350 

* 

Open for i — ••••.. • 

361 


Open for i.-tU-M.;-, . >= writing. 

35“ 

iLY 

Open for uniting only. 


Table <1-7 - Weak lor l)*e With File Access Modes 

CondtKiit , Poe ription 

D_ACCMODE MV.sk for file ocean modes. 


.2.2 Descri). 

i'he Auction /fct./.’i •/ uviilus <b>- control over open files. The argument fildes is a 
file descriptor. 

The svaSW.V am ilehned in the header <fcntl.h> (see 6.5.1), 

which shaii uit-'i i . 

f Dl/Pr > ... <:'e descriptor that is the lowest numbered avail- 

, ’y on n) file descriptor greater than or equal 
!:•. tut ihir.i . .•(■iiment, arj, taken as an integer of type inf. The 
= . ' refers to the same open file description as 

; . descriptor and shares any locks. 

. .; 1 ji /jlated with the new file descriptor is 
id UI koap the file open across calls to the exec family of 
:■ ' fictions. 



P JGK 

: )h\ flags, as defined in Table 6-2, that are 

3 


. . : with* ‘(be file descriptor fildes. File descriptor flags 

374 


are associated with a single file descriptor and do not affect 

376 


other hie descriptors that refer to the same file. 

376 

7 

FjShi 

! ... •:V;c> des<T’ ■ f. as defined in Table 6-2, that are 


; to tri . - ih-Vd argument, arg, taken as type 
.... .• flag is zero, the file shall remain open 

i ■ uitiona; otherwise, the file shall be closed upon 

>0 


*ul t^ecuiion of an exec function. 

>1 

F f' • • 

Hag*, as defined in Table 6-5, and file access 
iption associated with fildes. The 

383 


a Table 6-6 can be extracted from the 

384 


return value using the mask 0_ACCMODE, which is defined at 

386 


< fcntl . h>. File status flags and file access modes are associ- 

386 


ated with the open file description and do not affect other file 

387 


descriptors that refer to the same file with different open file 

388 


descriptions. 
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6 Input and Output Primitives 


6.5 Control Operations on Files 
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ISO/IE C 9946-1: 1990 
IEEE Std 1003.1-1990 

information TECHNOLOGY— POSIX 

5.6.1.1 <»y*/atat.h> File Types 

The following macros shall test whether a file is of the specified type. The value 
m s upplied to the macros is the value of strode from a stat structoe The macro 
evaluates to a nonzero value if the test is true, zero if the test is false. 

S_ISDIR(m) Test macro for a directory file. 

S_ISCHR(m) Test macro for a character special file. 

S_ISBLK(m) Test macro for a block special file. 

S_ISREG{m) Test macro for a regular file. 

SjSFIFCKm) Test macro for a pipe or a FIFO special file. 

5.6.1.2 <sya/stat.h> File Modes 

The file modes portion of values of tvoe made I 

bit-encoded with the following masks and bits: ’ ' " 


S_IRWXU 


S_1RWXG 


S_IRWXO 


S_ISUID 


SJSGID 


Read, write search (if a directory), or execute (other*™.) pen; 
sions mask for the file owner class. 

S_IRUSR Read permission hit for the file owner class. 

S_IWUSR Write permission bit for the file owner clues. 

S-IXUSR Search (if a directory) or execute 'other. , ; 
missions bit for the file owner class. 

Read, write, search (if a directory), or execute (otherwise', ■ 
sions mask for the file group class. 

SJRGRP Read permission bit for the fde group class. 

S.IWGRP Write permission bit for the file group class. 

S-IXGRP Search (if a directory) or execute (other,, . .. 
missions bit for the file group class. 

Read, write, search (if a directory), or execute (otherwise! n»mi, . 
sions mask for the file other class. 

S_1R0TH Read permission bit for l'.. 

S—IWOTH Write permission bit for the file . , 

S_1X0TH Search (if a direcio . r execute {other., 
missions bit for the file other clas.c 
Set user ID on execution. The effec t 
shall be set to that of the owner of ti < 
a program (see exec). On a regular file, lit, 
on any write. 

Set group ID on execution. Set effective group ID on the process to 
the group of the fi e when the file is run as a program (see exec). 
On a regular file, this bit should be cleared on any write. 
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5 Files and Directories 
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/s/stat • h> Time Entries 

l ated fields $itit are as follows: 

Accessed fore* nple, readi). 

une Modified 'i-v for example, write (). 

• # Cha'. i • . u ••r.'Otiple, chwiotli ). 


given h 


oss-livforeiites 

hownO, 5.6.5; creatQ, 5.3.2; exec, 3.1.2; linkO, 5.3.4; mkdirO, 
«!• nipe (), 6.1.1; rea,H i, 6.4.1; unlinkO. 5.5.1; utrneO, 5.6.6; 
• r. Standard {211. 


. oil itu 0 1 • ' . \ id UOC ffti Ui 

name leading to the file must be searchable. The stat() function obtains informa- 
tion about the named file and writes it to the area pointed to by the buf argument. 

Similarly, the fstati) function obtains information about an open file known by the 
file descriptor fildes. 


5.6 File Characteristics 


ISO/IEC 9945-1: 1990 

IEEK Std 1003.1-1990 INFORMATION TECHNOLOGY-POSIX 

5.6. 1.1 <sys/stat . h> File Types 

The following macros shaU test whether a file is of the specified type. The value 
m supplied to the macros is the value of stjnode from a stat structure. The macro 
evaluates to a nonzero value if the test is true, zero if the test is false. 

SjSDIR(m) Test macro for a directory file. 

SjSCHR(m) Test macro for a character special file. 

SjSBLK(m) Test macro for a block special file. 

S_ISREG(in) Test macro for a regular file. 

SjSFIFCXm) Test macro for a pipe or a FIFO special file. 

5.6. 1.2 <sys/atat . h> File Modes 

hit' eSL m H d ^w^ ti ? 1 .. 0f ValU0S ° f type modeJ < such 88 the st_mode value, are 
bit-encoded with the following masks and bits: 

SJRWXU Read, write, search (if a directory), or execute (otherwise) permis- 
sions mask for the file owner class. 

SJRUSR Read permission bit for the file owner class. 

S JWUSR Write permission bit for the file owner class. 

S_IXUSR Search (if a directory) or execute (otherwise) per- 
missions bit for the file owner class. 

S JRWXG Read, write search (if a directory), or execute (otherwise) permis- 

sions mask for the file group class. 

S JRGRP Read permission bit for the file group class. 4 

SJWGRP Write permission bit for the file group class. 

SJXGRP Search (if a directory) or execute (otherwise) per- 
missions bit for the file group class. 

S_IRWXO Read, write, search (if a directory), or execute (otherwise) permis- 
sions mask for the file other class. 

S-IROTH Read permission bit for the file other class. 

SJWOTH Write permission bit for the file other class. 

S JXOTH Search (if a directoiy) or execute (otherwise) per- 

missions bit for the file other class. 


S_ISUID 


SJSGID 


Set user ID on execution. The effective user ID of the process 
shall be set to that of the owner of the file when the file is run as 

a program (see exec). On a regular file, this bit should be cleared 
on any write. 

Set group ID on execution. Set effective group ID on the process to 
the group of the file when the file is run as a program (see exec). 
On a regular file, this bit should be cleared on any write. 
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689 The bits defined by SJRUSR, S.IWUSR, S_IXUSR, S_ 

690 SJROTH, SJWOTH, SJXOTH, SJSUID, and SJSGID 

691 shall be the bitwise inclusive OR of SJRUSR, SJWU5 

692 shall be the bitwise inclusive OR of S JRGRP, SJWGI 

693 shall be the bitwise inclusive OR of SJROTH, SJWI 

694 mentations may OR other implementation-defined bit 

695 and SJRWXO, but they shall not overlap any of the ot 

696 of ISO/IEC 9945. The file permission bits are defined 1 

697 the bitwise inclusive OR of S JRWXU, S JRWXG, and S 

698 5.6.1.3 <sys/stat.h> Time Entries 

699 The time-related fields of struct stat are as follows: 

700 st_atime Accessed file data, for example, readi) 

i 701 stjntime Modified file data, for example, writei, 

702 st_ctime Changed file status, for example, chmi 

703 These times are updated as described in 2.3.5. 

704 

V 

705 Times are given in seconds since the Epoch. 

706 5.6.1.4 Cross-References 

707 chmodi), 5.6.4; chowni), 5.6.5; creati), 5.3.2; exec, 3.1.5 

708 5.4.1; mkfifoO, 5.4.2; pipei), 6.1.1; readi,), 6.4.1; unlink 

709 write (), 6.4.2; remove () [C Standard (2)]. 


710 5.6.2 Get File Status 

711 Functions: stati), fstati) 

712 5.6.2.1 Synopsis 

713 tinclude <sys/types -h> 

714 tinclude <sys/stat.h> 

716 int stat (const char *path, struct stat *buf) ; 

716 int fstat(int fildes , struct stat *buf) ; 

717 5.6.2.2 Description 

718 The path argument points to a pathname naming a fi 

719 permission for the named file is not required, but all di 

720 name leading to the file must be searchable. The staU 

721 tion about the named file and writes it to the area poin 

722 Similarly, the fstati) function obtains information abot 

797 HpS0T*ir>^or filsJnn 
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307 

308 

309 

310 

311 

312 

313 

314 

315 

316 

317 
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322 

323 

324 

325 

326 

327 

328 
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5.3. 3.3 Returns 
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The file permission bits in the value returned by umask () shall be the previous 
value of the file mode creation mask. The state of any other bits in that value is 
unspecified, except that a subsequent call to umask () with that returned value as 
cmask shall leave the state of the mask the same as its state before the first call, 
including any unspecified (by this part of ISO/IEC 9945) use of those bits. 

5.3 .3.4 Errors 

The umask () function is always successful, and no return value is reserved to 
indicate an error. 

5.3.3.5 Cross-References 

chmodO, 5.6.4; creatO, 5.3.2; mkdir{), 5.4.1; mkfifo(), 5.4.2; open(), 5.3.1; 
<sys/stat .h>, 5.6.1. 


318 5.3.4 Link to a File 

319 Function: linkO 


5.3. 4.1 Synopsis ' 

mt link (const char * existing , const char *new) ; 

5.3.4.2 Description 

The argument existing points to a pathname naming an existing file. The argu- 
ment new points to a pathname naming the new directory entry to be created. 
Implementations may support linking of files across file systems. The link{) func- 

shalx atomicaiiy create a new link for the existing file and increment the link 
count of the file by one. 

If the link () function fails, no link shall be created, and the link count of the file 

ohc'l VAW AfM "* • . . 1 1. ' A I « MV 
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337 

5.3.4.S Returns 

338 

339 

Upon successful < 
value of -1 is retu: 

340 

5.3. 4.4 Errors 

341 

342 

If any of the follov 
errno to the corres 

343 

344 

345 

346 

347 

[EACCES] 

348 

[EEXIST] 

349 

350 

[EMLINK] 

351 

362 

353 

354 

| 

355 

356 

357 

[ENAMETOOLI 

[EN0ENT] 

358 

[ENOSPC] 

359 

[ENOTDIR] 

360 

361 

362 

[SPERM] N 

363 

364 

[EROFS] 


Recognized as an 
American National 
Standard (ANSI) 


Inf 

Ope 

Syste 


a 


i 


ISBN 1-55937-061-0 


Library of Congress Catalog Number 90-084554 


, I] 

I 


Quote in 8.1.2.3 on Returns is taken from X3.159-1989, 
developed under the auspices of the American National Standards 
Accredited Committee X3 Technical Committee X3J11, Computer and 
Business Equipment Manufacturers Association (CBEMA), 

311 First St, N.W., Suite 500, Washington, DC 20001. 


Abstract: IS 1 
nology — Portal 
tion Program 1 
dards for appli 
cations interfa 
and process m; 
standard is sta 

Keywords: AI 



The Source for UNIX Standardization Information 


ISO/IEC 9945-1 : 1990 (POSIX .1) defines 
a standard operating, system interface and 
environment based on the UNIX Operating 
System. It supports applications portability 
at the source-code level between multi- 
vendor computer systems. 

POSIX. 1 establishes a set ot basic ser- 
vices fundamental to the efficient con- 
struction ot applications programs. Access 
to these services is provided through an 
operating system using the C program- 
ming language. The OS interface estab- 
lishes standard semantti^and syntax, and 
allows lor application developers to design 
portable applications. 

Complementing existing standards relat- 
ed to computer languages, database 
management, and computer graphics, 
POSIX. 1 is designed for and used by both 
application developers and system imple- 
mentors. It provides a solid base for the 
systems procurement and evaluation pro- 
cesses. By specifying POSIX.1 confor- 


mance, system purchasers can produc- 
tively manage their software environments 
to achieve the benefits of applications 
portability. Likewise, hardware and soft- 
ware suppliers and developers will have a 
clear specification to follow in designing 
their systems and applications tor the 
open software environment. 

POSIX.1 constitutes a major step in the 
industry toward providing a comprehen- 
sive standardized applications environ- 
ment. The IEEE's POSIX Committee is 
continuing POSIX-related standards work 
in areas such as POSIX-based Open Sys- 
tem Environment (IEEE Project 1003.0), 
Shell and Utilities (IEEE Project 1003.2), 
Test Methods (IEEE Project 1003.3), Real- 
Time Systems Interfaces (IEEE Project 
1003.4), An Ada Language Binding for 
POSIX (IEEE Project 1003.5), and a FOR- 
TRAN Language Binding to POSIX (IEEE 
Project 1003.9). 

UNIX is a registered trademark olATST. 


IEEE Seminars . . . Keeping You Competitive Through Standards 


If you detine architectures for large distribution systems, set standards policy for your orga- 
nization, or evaluate functional, performance, and integrity requirements, be sure to regis- 
ter for the new IEEE POSIX Seminar. 

In Spring 1991, IEEE is launching a 2-day seminar based on the IEEE Project 1003.0, 
Guide to POSIX Open Systems Environments, and other IEEE projects concerning open 
systems. You will learn about frameworks and profiles for Information Technology stan- 
dards, and how they directly apply to your organization. 

For more Information, call toll free In the USA at 1 (800) 878-IEEE and ask for 
Seminars on Standards. Or write to IEEE Standards Seminars, 445 Hoes Lane, PO 
Box 1331, Plscataway, NJ 08855-1331 USA. 
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• A comprehensive applications environment 

• Applications portability at the source-code level 
■ - v j i: ' An applications interface to 10. file system access. 

"■ and process management facilities 
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• Software Applications Developers 
• System Designers Engineers 
• Hardware and Software Purchasers 
• End users operating a UNIX 
OS environment 

UNIX is a registered trademark at. AT 6 r 
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